Selbstdokumentierender Code gegen Javadocs?

Vor kurzem habe ich daran gearbeitet, Teile der Codebasis, mit denen ich mich derzeit befasse, zu überarbeiten - nicht nur, um sie selbst besser zu verstehen, sondern auch, um es anderen zu erleichtern, die an dem Code arbeiten.

Ich neige dazu, mich auf die Seite des Denkens zu lehnen, dass selbstdokumentierender Code nett ist . Ich denke nur, es ist sauberer und wenn der Code für sich selbst spricht, na ja ... Das ist großartig .

Auf der anderen Seite haben wir Dokumentation wie Javadocs. Das gefällt mir auch, aber es besteht ein gewisses Risiko, dass Kommentare hier veraltet sind (und natürlich auch Kommentare im Allgemeinen). Wenn sie jedoch auf dem neuesten Stand sind, können sie zum Beispiel äußerst nützlich sein, um einen komplexen Algorithmus zu verstehen.

Was sind die Best Practices dafür? Wo ziehen Sie die Grenze zwischen selbstdokumentierendem Code und Javadocs?

Selbstdokumentierender Code (und In-Code-Kommentare) und Javadoc-Kommentare haben zwei sehr unterschiedliche Zielgruppen.

Der Code und die Kommentare in der Codedatei sind für Entwickler bestimmt. Sie möchten hier auf ihre Bedenken eingehen - machen Sie es einfach zu verstehen, was der Code tut und warum der Code so ist, wie er ist. Dies wird durch die Verwendung geeigneter Variablennamen, Methoden, Klassen usw. (selbstdokumentierender Code) in Verbindung mit Kommentaren erreicht.

Javadoc-Kommentare richten sich in der Regel an Benutzer der API. Dies sind auch Entwickler, aber sie kümmern sich nicht um die interne Struktur des Systems, sondern nur um die Klassen, Methoden, Eingaben und Ausgaben des Systems. Der Code ist in einer Blackbox enthalten. Diese Kommentare sollten verwendet werden, um zu erläutern, wie bestimmte Aufgaben auszuführen sind, welche Ergebnisse von Operationen erwartet werden, wann Ausnahmen ausgelöst werden und welche Eingabewerte dies bedeuten. Angesichts einer von Javadoc generierten Dokumentation sollte ich in der Lage sein, die Verwendung Ihrer Schnittstellen vollständig zu verstehen, ohne jemals eine Codezeile zu betrachten.

Code sagt wie . Kommentare sagen warum und vielleicht sogar warum nicht .

Es ist Ihre Aufgabe, zukünftige Leser und Betreuer Ihres Codes zu informieren. Geben Sie alles, was Sie können, in den Code und den Rest in die Kommentare ein.

Beachten Sie, dass die am schwersten zu erfassenden Dinge die Designentscheidungen sind - denken Sie auch daran.

Die Verwendung von Javadocs macht keinen wirklichen Unterschied - da die generierten Dokumente den Namen Ihrer Funktionen zusammen mit dem Text aus den Kommentaren enthalten, gibt es absolut keinen Grund, warum Sie irgendetwas in den Kommentaren wiederholen sollten, das aus dem Funktionsnamen selbst hervorgeht.

Wenn Sie auf der anderen Seite eine Funktion haben, bei der Sie sich zuerst die Implementierung ansehen müssen, um zu verstehen, wozu sie gut ist (und Javadocs diese Informationen nicht zur Verfügung stellen), ist der Code IMHO nicht selbstdokumentierend, egal wie klar die Umsetzung ist.

Ich denke, dass bei Javadocs die Dinge die gleichen sind wie bei jeder anderen Dokumentation. Die Hauptregel lautet:

folge dem Publikum

Sie viele Leute lesen Ihre javadocs? Wenn ja, ist es sinnvoll, Anstrengungen zu unternehmen, um es richtig zu machen.

Überspringen Ihre Leser in der Regel das Lesen von Code, um Javadocs zu studieren? Wenn ja, ist es doppelt so sinnvoll, sich darum zu bemühen, es gut zu schreiben.

• Genau das ist bei der JDK-Dokumentation der Fall . Vermutlich hat sich Sun / Oracle viel Mühe gegeben, und es scheint, dass sich API-Dokumente auszahlen, wenn sie von der Community häufig verwendet werden.

Nun, ist es dein Fall? Wenn nicht, überlegen Sie zweimal, ob die in Javadocs investierten Anstrengungen gerechtfertigt sind.

Hören Sie, wie oben bereits erwähnt, dem Publikum zu, um den Weg zu finden.

• Wenn Sie aktive Beschwerden über unzureichende Dokumentation hören, erwägen Sie, in deren Verbesserung zu investieren.
   
  Wenn Sie auf der anderen Seite nur Entwickler hören, die sich über Kopfnuss-Regeln beschweren, die sie dazu zwingen, Zeit mit nutzlosem Tippen zu verschwenden, dann ist die Wahrscheinlichkeit groß, dass Ihre Javadocs-Bemühungen wie eine Investition in Subprime-Hypotheken sind . Denken Sie stattdessen an bessere Investitionen.

Ich möchte nur auf die Sorge eingehen, dass Javadoc-Kommentare veraltet sein könnten. Während @JonathanMerlet zu Recht sagt, dass Javadoc stabil sein sollte, können Sie auch helfen, indem Sie Javadoc und Kommentare sowie Code während der Peer-Überprüfung überprüfen. Stimmen die Kommentare mit dem Code überein? Wenn nicht, was falsch ist, und darauf bestehen, dass der Entwickler das Problem behebt. Versuchen Sie, andere Entwickler dazu zu ermutigen, dasselbe zu tun. Dies hält nicht nur die externe Dokumentation (Javadoc-Kommentare) auf dem neuesten Stand, sondern auch alle regulären Codekommentare. Dies hilft Entwicklern, die nach dem Refactoring mitarbeiten, den Code schneller und einfacher zu verstehen und ihn in Zukunft viel einfacher zu warten.

Ich denke, dass Javadocs für die Teile geeignet ist, die stabil bleiben sollen (API), so dass das Risiko, dass Kommentare nicht mehr aktuell sind, minimiert wird, wohingegen selbstdokumentierender Code für häufig geänderte Teile (Implementierung) großartig ist. Natürlich können sich APIs im Laufe des Projekts ändern, aber wenn der Header direkt vor der Deklaration angezeigt wird, ist es nicht so schwierig, beide zu synchronisieren (im Vergleich zu Kommentaren in mehreren Zeilen, die mehrere Codezeilen erklären).