Sollten Sie alles oder nur die meisten dokumentieren?

Es scheint ein wenig umstritten zu sein, alles zu dokumentieren, einschließlich der "JavaBean" -Syntax von Gettern und Setzern für Felder: Die Leute sagen, dass es unnötig lange und sich wiederholende DRY-Unterbrechungen gibt (wiederholen Sie sich nicht) , dass die Namenskonvention alles erklären sollte , und es wirft Code / Dokumentation. Manchmal funktionieren diese Argumente. Aber manchmal haben Sie Folgendes:

Oben ist es üblich, Open-Source-Projekte zu erstellen, die diesen Grundsätzen kühn folgen. Ihnen bleibt eine völlig nutzlose Dokumentation . Das erklärt nichts über das, was darunter vor sich geht, die möglichen Auswirkungen oder sogar den erwarteten Wert (könnte er null oder nie null sein? Ich weiß es nicht; das Javadoc sagt es mir nicht).

Wann sollte ich also dokumentieren? Dokumentiere ich alles, auch wenn es gelegentlich Code überfüllt? Oder dokumentiere ich nichts, da es in meinen Augen "offensichtlich" ist?

Dokumentieren Sie alles , was zu dokumentieren sinnvoll ist .

In einer idealen Welt würden Sie alles dokumentieren. Wir auf der Erde haben jedoch Fristen, Sonderangebote, Besuche bei Familien und Freunden, Urlaubstage, nur 24 Stunden am Tag und nur 365 Tage im Jahr. Es bleibt einfach nicht genug Zeit, um alles zu dokumentieren. Dokumentieren Sie also optimalerweise alles, was Sie können (Sie werden es nicht schaffen), aber holen Sie sich das Beste für Ihr Geld, indem Sie:

• Machen Sie Code lesbar und Methodensignaturen so offensichtlich wie möglich, damit die Wahrscheinlichkeit geringer ist, dass eine Dokumentation erforderlich ist.
• Die dunkelsten Dinge zuerst dokumentieren. Helfen Sie anderen, indem Sie die verrückten Hacks dokumentieren, die Sie machen mussten, um Dinge aus der Tür zu bekommen.
• Dokumentieren Sie das Warum vor dem Was - Kommentieren Sie nicht, was etwas bewirkt, z. B. "Durchlaufen Sie die Kundendatensätze, bei denen der Saldo kleiner als Null und die Bewertung kleiner als Eins ist, und fügen Sie sie der Liste" exemptCustomers "hinzu". Dokumentieren Sie, warum Sie sie in Klartext (oder in der Sprache Ihres Teams) zur Liste hinzufügen, z. B. "Da diese Kunden einen negativen Kontostand und niedrige Bewertungen aufweisen, verursachen sie einen Geldverlust. Schließen Sie sie daher vom Check-out aus.

Dokumentieren Sie so lange, bis Sie sehen können, wie jemand anderes es liest, ohne dass Sie etwas erklären müssen.

In der vergangenen Woche gab es einen großartigen Artikel über Dokumentation bei The Daily WTF. Ich denke, es sagt alles, also lasse ich einfach den Link:

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

Grundsätzlich heißt es, dass Sie etwas nicht dokumentieren sollten, wenn es nicht nützlich ist (einige Dokumentationen verbleiben nur in einer Schublade) und die geringste Menge an Informationen dokumentieren sollten, die zum Verständnis eines bestimmten Teils des Projekts erforderlich sind. Zu viel Dokumentation verwirrt den Leser.

Kommt wirklich darauf an, wie lesbar der Code für das Publikum ist, das ihn liest. Finden Sie heraus, wer die Zielgruppe für das Lesen Ihres Codes ist, und lassen Sie jemanden, der diesem Profil entspricht, Ihren Code lesen.

Ein anderer Ansatz wäre, nach einer Woche Ihren eigenen Code zu überprüfen und festzustellen, ob Sie noch verstehen, was Sie getan haben. Wenn Sie dies nicht tun, dokumentieren Sie den Code und überprüfen Sie ihn in etwa zwei Wochen.

Ich schätze eine klare und umfassende Dokumentation, aber es gibt nichts Schöneres als selbstdokumentierenden Code. Das Fazit (für mich) lautet also:

Seien Sie der (Quellcode-) Dokumentation gegenüber sehr misstrauisch. Versuchen Sie, es überflüssig zu machen, indem Sie den Code verbessern, aber scheuen Sie sich nicht, wenn nötig klar und vollständig zu dokumentieren.

Natürlich kann unter bestimmten Umständen eine Dokumentation aus anderen Gründen als "Erklären der Funktionsweise des Codes" erforderlich sein (z. B. große Teambasis, Organisationsstandards usw.).

Mein Vorschlag zur Dokumentation ist, dass, wenn der Code etwas Besonderes enthält, dies zu einem Dokument gehört, das auf dem neuesten Stand gehalten werden sollte. Ich bin der Meinung, dass etwas auf eine bestimmte Art und Weise getan wird, die Nebenwirkungen haben kann, die beachtet werden sollten, z. B. rekursiv, um sicherzustellen, dass Enkelelemente beim Durchlaufen eines Knotenbaums verarbeitet werden einen Test für alle Nachkommen durchzuführen. Zu artikulieren, warum etwas auf eine bestimmte Weise getan wurde, kann ein guter Weg sein, um zu wissen, ob es einen guten Grund gab, etwas zu verwenden.

Kurz gesagt, die Dokumentation soll den Entwicklern jetzt und den Betreuern in Zukunft helfen.

Wenn Sie sich an diese einfache Maxime erinnern, sollte die Dokumentationsebene selbstdefinierend sein.

Dokumentation ist aus Dokumentationsgründen eine Zeitverschwendung. Es ist jedoch hilfreicher, heute zu erklären, was Sie tun, als dass jemand Ihren Code in fünf Jahren neu entwickeln muss.

Persönlich gehe ich davon aus, alles zu dokumentieren . Dh beim Codieren überlege ich mir an jeder Stelle, ob Dokumentation Mehrwert bringen würde. Meistens lautet die Antwort Ja für genau die Arten von Einschränkungen und Domänenkenntnissen, die in der ursprünglichen Frage erwähnt wurden. ZB Null-Fähigkeit, eindeutige Einschränkungen, Interpretation des Feldes im weiteren Bereich.

Um Doppelarbeit zu vermeiden, neige ich dazu, die wichtigsten API-Klassen mit dieser Art von Informationen zu dokumentieren. Dokumentieren Sie dann nur Implementierungen und Interna, bei denen nicht offensichtliches oder inkonsistentes Verhalten vorliegt. Ich finde, dass dies gut funktioniert, da die Benutzer der API die meiste Hilfe und Dokumentation benötigen. Es ist im Allgemeinen ungefährlich anzunehmen, dass Personen, die die Implementierung ändern, die API kennen, also über dieses Wissen verfügen.

Ich neige auch dazu, nur die Getter zu dokumentieren. Ich dupliziere keine Dokumentation für Setter, Felddefinitionen und Konstruktorparameter. Ich dokumentiere nur nicht offensichtliches Verhalten wie Standardeinstellungen an diesen Stellen. Jegliches Verhalten, das aus der Getter-Dokumentation abgeleitet werden kann, ist nicht dokumentiert. Wenn der Getter beispielsweise als nie zurückgegebener Nullwert dokumentiert ist, dokumentiere ich im Allgemeinen nicht, dass Sie dem Setter keinen Nullwert übergeben können, es sei denn, es gibt einen Standardwert.

Einige Leute markieren diesen Akt der "Prüfung der Dokumentation" gerne, indem sie leere Kommentare hinzufügen, wenn sie die Dokumentation als unnötig erachteten. Ich mag diese Übung nicht, da sie den Code nur überfüllt und in die Quere kommt.