Selbstdokumentierender Code gegen Javadocs?

18

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?

Andreas Johansson
quelle

Antworten:

24

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.

Thomas Owens
quelle
+1, das ist ein guter Anruf. Ich denke, mein Hauptargument dabei ist, dass ich es nicht als zwei verschiedene Zielgruppen sehe, aber Sie haben Recht.
Andreas Johansson
1
@Andiaz - Ich finde es nützlich, zwischen äußeren Rändern des Systems (wie einer Service-API) und Klassen darin zu unterscheiden. Ich arbeite oft an Projekten, bei denen es die Konvention ist, alle öffentlichen Methoden zu javadokieren, aber ich achte sehr viel mehr auf die äußeren Klassen, um einen Hinweis darauf zu geben, wie die Klasse (und das System) verwendet werden sollten. Bei den inneren Klassen gehe ich davon aus, dass der Leser mehr Domänenkenntnisse hat und das Javadoc minimiert, sodass die Methodennamen mehr für sich selbst sprechen.
Steve Jackson
3
@SteveJackson Ich stimme jedoch zu, dass ich mehr Javadocs (auch für private Mitglieder) verwendet habe, da IDEs (mindestens Eclipse und NetBeans) die Javadoc-Kommentare in den QuickInfos zur Code-Vervollständigung anzeigen. Natürlich sind sie nicht so sauber wie die öffentlich zugänglichen Oberflächen, sondern geben anderen Entwicklern Tipps und Hinweise.
Thomas Owens
24

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.


quelle
2
+1: Es ist nicht "entweder oder" in einem exklusiven Sinne. Es ist beides in einem inklusiven Sinne.
30.
Dem stimme ich definitiv zu. Gibt es noch etwas, das Sie besonders bei Javadocs beachten sollten? Ich kann mir vorstellen, dass die Beschreibung der Funktionsweise einer Methode beispielsweise für APIs nützlich sein könnte.
Andreas Johansson
Javadocs sind von den meisten IDEs aus sehr leicht zugänglich. Erleichtern Sie die Navigation zu weiteren Informationen.
+1: Die besten Kommentare, die ich gesehen habe, enthielten Verweise auf die Artikel, in denen die verwendeten Algorithmen ausführlich besprochen wurden. Dies kann nicht in Variablen- / Methodennamen selbst dokumentiert werden und gehört nicht unbedingt in Doc-Kommentare, da der Algorithmus Teil der Implementierung und nicht der Schnittstelle ist .
Donal Fellows
4

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.

Doc Brown
quelle
3
+1 Mein Favorit ist, wenn der Buchungskreisstandard dokumentierte Methoden erfordert, aber jeder einen Generator verwendet, der nur wiederholt, was der Code bereits sagt. Langweilig und nutzlos.
Kryptic
1

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.
Mücke
quelle
0

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.

Eric Hydrick
quelle
-1

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).

Jonathan Merlet
quelle