Ziehen Sie Beispiele der Dokumentation vor. Ist es ein Verhaltensproblem?

Wenn ich auf eine neue API oder Programmiersprache oder sogar auf einfache Linux- Manpages stoße , habe ich sie (seit ich mich erinnere) immer gemieden und mich stattdessen träge auf Beispiele verlassen, um neue Konzepte zu verstehen.

Unbewusst vermeide ich Dokumentation / APIs, wenn sie nicht einfach oder kryptisch oder einfach nur langweilig sind. Es ist Jahre her, seit ich mit dem Programmieren angefangen habe, und jetzt habe ich das Gefühl, ich muss mich verbessern, da ich jetzt merke, dass ich mehr Schaden anrichte, indem ich auf das Lesen von kryptischen / schwierigen Dokumenten verzichte, da es immer noch millionenfach besser ist als Beispiele als der Beamte Dokumentation hat mehr Abdeckung als jedes Beispiel da draußen. Auch nach der Erkenntnis, dass Beispiele als "Mehrwert" anstatt als "primäre" Lernquelle behandelt werden sollten.

Wie breche ich diese schlechte Angewohnheit als Programmierer ab oder überdenke ich?

Die Gewohnheit, sich bevorzugt auf Beispiele zu verlassen, hat nichts auszusetzen: Für Sie ist es nur der schnellste Weg, eine Antwort zu erhalten. Darüber hinaus sind Beispiele visuell. Es ist einfacher, ein Beispiel visuell zu analysieren, als Textabschnitte zu lesen und die benötigten Informationen zu extrahieren.

Beispiel:

Um die Produkte aufzulisten, sollte man die IndexAktion des ProductsControllers verwenden, da GETdies hier das einzig mögliche Verb ist (siehe [Produkte beeinflussen] für weitere Informationen zu den Aktionen, die zum Erstellen, Ändern und Löschen der Produkte aus der Datenbank verwendet werden).

Um detaillierte Informationen zu einem bestimmten Produkt zu erhalten, hängen Sie seine eindeutige Kennung an das Ende der URI an. Wenn Sie die Liste aller verfügbaren Produkte erhalten möchten, fügen Sie nichts hinzu. Sie können auch Filter verwenden, wie im Abschnitt [REST-Filter zur Datenauswahl] des Handbuchs beschrieben. Beachten Sie, dass die Liste der Produkte auf tausend Artikel beschränkt ist. [Paginierung] kann verwendet werden, um die gesamte Liste durchzugehen, da jede Seite immer noch auf tausend Elemente beschränkt ist.

Möglicherweise möchten Sie den Service auch dazu zwingen, die vorrätigen Mengen zu aktualisieren. Dies erfolgt durch Setzen von refresh-quantitiesauf eins.

ist detailliert, aber langweilig und kaum lesbar. Die Tatsache, dass Sie Links folgen müssen, macht die Sache noch schlimmer. Wenn wir einige Beispiele anhängen, wird es viel einfacher zu verstehen:

GET-Produkte / Index /
GET-Produkte / Index / 12345 /
GET-Produkte / Index /? Überspringen = 100 & nehmen = 20
GET-Produkte / Index /? Kategorie = 12
GET-Produkte / Index /? Preis = 0..39.90
GET-Produkte / Index /? category = 12 & skip = 100 & take = 20

Die Tatsache, dass Sie nur die Beispiele verwenden, kann ein Problem sein. Hören Sie nicht einfach auf, die Beispiele zu verwenden, aber denken Sie daran, dass eine ausführlichere Dokumentation hilfreich sein kann, wenn Sie die Idee haben. Das obige Beispiel zeigt beispielsweise nicht, dass die Liste der Produkte auf 1 000 beschränkt ist: Sie müssen die Dokumentation dazu lesen.

Wann wissen Sie, dass Sie die Dokumentation lesen sollten?

Jedes Mal, wenn sich die API oder die Bibliothek nicht wie erwartet verhält. Sie greifen zum Beispiel nach dem Beispiel und führen Folgendes aus:

GET Products / Index /? Überspringen = 6000 & take = 3000

Aus irgendeinem Grund werden weniger als 3.000 Artikel zurückgegeben, während Ihre Datenbank über zwanzigtausend Produkte enthält. In diesem Fall verhält sich die API nicht so, wie Sie es erwartet haben. Daher ist es ein guter Zeitpunkt, die ausführliche Dokumentation zu lesen.

Informationen, die durch Dokumentation bereitgestellt werden, fallen in drei Kategorien:

• Rezept.
• Referenz.
• Expertenwissen.

Rezepte oder Beispiele schlagen eine Brücke zwischen der Problemdomäne und den Funktionen der Software. Die Referenz beschreibt einige Funktionen vollständig und ist nützlich, wenn Sie ein Rezept an einen bestimmten Fall anpassen möchten.

(Expertenwissen ordnet Konzepte der Problemdomäne Dokumentationskonzepten zu. Es ist nützlich, wenn Konzepte auf verschiedene Arten ausgedrückt werden können oder wenn Benutzer der Software keine Experten auf dem Gebiet sind.)

Wie breche ich diese schlechte Angewohnheit als Programmierer ab oder überlege ich mir etwas zu viel? Jegliche Weisheit von anderen Programmierern wird geschätzt.

Ich denke nicht, dass deine Angewohnheit schlecht ist. Wenn Sie eine API lernen, bekommen Sie zuerst eine Vorstellung davon, welche Probleme gelöst werden können und welche Methoden mit Hilfe von Rezepten (Ihren Beispielen) bereitgestellt werden. Die Referenzdokumentation hilft Ihnen dann, die Methoden auf spezielle Fälle abzustimmen.

Beispiele sind Dokumentationen. Ich denke nicht, dass es schlecht ist, wenn man sich mit dem API-Standpunkt vertraut macht. Wenn dies die einzige Dokumentation ist, die Sie sich ansehen, kann dies ein Problem sein. In den meisten Beispielen wird die Fehlerprüfung übersprungen, was zu übermäßig sprödem Code führen kann, wenn Sie die fehlenden Teile nicht erneut aus der Referenzdokumentation entnehmen.

Unterschiedliche Menschen lernen auf unterschiedliche Weise besser. Einige Leute sind wie Sie und lernen besser aus Beispielen. Einige Leute sind wie ich und lernen besser aus detaillierten Unterlagen. Beide in der Dokumentation zu haben, scheint die meisten Entwickler ziemlich gut abzudecken. Sprechen Sie mit einem Lehrer, er kann Ihnen ein halbes Dutzend Möglichkeiten nennen, wie Menschen lernen.