Muss ein Javadoc-Kommentar für JEDEN Parameter in die Signatur einer Methode geschrieben werden?

17

Einer der Entwickler in meinem Team glaubt, dass es notwendig ist, einen Javadoc-Kommentar für JEDEN Parameter in die Signatur einer Methode zu schreiben. Ich denke nicht, dass dies notwendig ist, und in der Tat denke ich, dass es sogar schädlich sein kann.

Zunächst einmal denke ich, dass Parameternamen beschreibend und selbstdokumentierend sein sollten. Wenn nicht sofort klar ist, wozu Ihre Parameter dienen, tun Sie es wahrscheinlich falsch. Ich verstehe jedoch, dass es manchmal unklar ist, wofür ein Parameter bestimmt ist. In diesen Fällen sollten Sie einen Javadoc-Kommentar schreiben, der den Parameter erläutert.

Aber ich denke, es ist unnötig, das für JEDEN Parameter zu tun. Wenn bereits klar ist, wofür der Parameter bestimmt ist, ist der Javadoc-Kommentar überflüssig. Sie schaffen nur zusätzliche Arbeit für sich. Darüber hinaus schaffen Sie zusätzliche Arbeit für alle, die Ihren Code warten müssen. Methoden ändern sich im Laufe der Zeit, und das Pflegen von Kommentaren ist fast so wichtig wie das Pflegen Ihres Codes. Wie oft haben Sie einen Kommentar wie "X macht Y aus Z-Gründen" gesehen, nur um festzustellen, dass der Kommentar nicht mehr aktuell ist und die Methode nicht einmal mehr X-Parameter akzeptiert? Es passiert die ganze Zeit, weil die Leute vergessen, Kommentare zu aktualisieren. Ich würde argumentieren, dass ein irreführender Kommentar schädlicher ist als gar kein Kommentar. Und damit ist die Gefahr einer Überkommentierung verbunden: Indem Sie unnötige Unterlagen erstellen, können Sie

Ich respektiere jedoch den anderen Entwickler in meinem Team und akzeptiere, dass er vielleicht Recht hat und ich mich irre. Aus diesem Grund stelle ich Ihnen, liebe Entwickler, die Frage: Ist es in der Tat notwendig, für JEDEN Parameter einen Javadoc-Kommentar zu schreiben? Angenommen, der Code ist in meiner Firma intern und wird von keiner externen Partei verwendet.

Gelassenheit
quelle
Viele Java-IDEs (insbesondere Intellij) kennzeichnen einen fehlenden Javadoc-Parameter als Dokumentationswarnung
Gary Rowe,
NetBeans und Eclipse auch.
Davor Ždralo

Antworten:

38

Javadoc-Anmerkungen (und in Microsoft Word XMLDoc) sind keine Kommentare , sondern Dokumentationen .

Kommentare können so spärlich sein, wie Sie möchten. Angenommen, Ihr Code ist zur Hälfte lesbar, dann sind normale Kommentare lediglich Wegweiser, um zukünftigen Entwicklern das Verständnis / die Pflege des Codes zu erleichtern, auf den sie bereits seit zwei Stunden starren.

Die Dokumentation stellt einen Vertrag zwischen einer Codeeinheit und ihren Aufrufern dar. Es ist Teil der öffentlichen API. Immer davon ausgehen , dass Javadoc / XMLDoc wird entweder in einer Hilfedatei oder in einer der automatischen Vervollständigung / Intellisense / Code-Completion - Popup beenden, und von Menschen beobachtet werden, sind nicht die Interna des Codes untersuchen , sondern nur wollen , verwenden sie für einen bestimmten Zweck aus ihre eigenen.

Argument- / Parameternamen sind niemals selbsterklärend. Sie denken immer, dass dies der Fall ist, wenn Sie den letzten Tag damit verbracht haben, an dem Code zu arbeiten, aber versuchen Sie, nach zwei Wochen Urlaub darauf zurückzukommen, und Sie werden sehen, wie wenig hilfreich sie wirklich sind.

Verstehen Sie mich nicht falsch - es ist wichtig, aussagekräftige Namen für Variablen und Argumente zu wählen. Dies ist jedoch ein Code-Problem, kein Dokumentationsproblem. Nehmen Sie den Ausdruck "selbstdokumentierend" nicht zu wörtlich. Das ist im Kontext der internen Dokumentation (Kommentare) gemeint , nicht der externen Dokumentation (Verträge).

Aaronaught
quelle
1
+1: Es ist genauso wichtig wie der Code selbst. Es gibt einfach keine guten automatisierten Tests.
S.Lott
Wenn die Parameter für eine Methode z. B. drei Paare von X- und Y-Koordinaten enthalten, die als benachbarte Ecken eines Parallelogramms interpretiert werden, ist es sinnvoller, sechs kleine Dokumente zu haben, eines für jeden Parameter, oder den Zweck des zu beschreiben Methode in Bezug auf Parallelogramm (x1, y1), (x2, y2), (x3, y3) und (x1 + x3-x2, y1 + y3-y2) [das letztere ist entgegengesetzt (x2, y2)]? Wenn der Zweck der Methode in Parameternamen definiert ist, würde ich eine zusätzliche Dokumentation der Parameter in vielen Fällen für überflüssig halten.
Supercat
1
@supercat: Ich würde argumentieren, dass Sie in einem solchen Fall ein Refactoring durchführen sollten, sodass Sie einen einzelnen Datentyp Pointhaben und die Funktion einfach drei Points(oder besser noch ein Array / iterierbares davon) benötigt. Je mehr Parameter eine Methode hat, desto unhandlicher ist der Aufruf und desto instabiler wird ihre Spezifikation im Laufe der Zeit.
Aaronaught
@Aaronaught: Das hängt sehr davon ab, wie die Methode angewendet wird. Eine Überlastung, die drei Pointund eine Überlastung, die eine empfängt Parallelogram, kann hilfreich sein, wenn viele Anrufer solche Dinge passieren könnten. Wenn jedoch viele PointInstanzen zu keinem Zweck erstellt würden, sondern nur einmal an die Methode übergeben würden, würde das Erstellen der Objekte das Lesen von Code verlangsamen und erschweren. Wenn eine Sprache Aggregate unterstützt, die sich wie ein Bündel von Werten verhalten, die mit Klebeband zusammengehalten werden, und man einen Parameter des Aggregattyps nur bis ...
supercat
Wenn Sie die Werte in geschweifte Klammern setzen, kann dies sowohl unter dem Gesichtspunkt der Leistung als auch der Lesbarkeit von Vorteil sein. Java hat kein solches Konzept; Eine JVM-basierte Sprache könnte so etwas effizient für Parameter unterstützen (ein Parameter Point p1könnte übersetzt werden int p1_x, int p1_y), aber die JVM hat keinen effizienten Mechanismus für eine Funktion, um so etwas zurückzugeben.
Supercat
12

Entweder alles kommentieren oder nichts kommentieren (offensichtlich ist es eine viel bessere Wahl, alles zu kommentieren). Denken Sie an jemanden, der Ihren Code verwendet und entweder Ihre API direkt in Ihrer Quelldatei oder in einer generierten Dokumentdatei (dh Sauerstoffausgabe) überprüft. Inkonsistenzen führen im Allgemeinen zu Verwirrung, was dazu führt, dass Zeit zum Durchsuchen der Quelle aufgewendet wird, um herauszufinden, warum etwas nicht kommentiert wurde. Dies führt zu Zeitverschwendung, die hätte vermieden werden können, wenn der Parameter gerade erst kommentiert worden wäre.

Denken Sie daran: Etwas, das für Sie sinnvoll ist, kann von jemand anderem völlig anders interpretiert werden, egal wie profan Sie es finden (denken Sie an jemanden, der nicht so gut Englisch kann und versucht, Ihren Code zu verstehen).

Wenn der andere Entwickler die Wichtigkeit betont, alles zu dokumentieren, dann muss genauso viel Gewicht (wenn nicht noch mehr) darauf gelegt werden, die Dokumentation auf dem neuesten Stand zu halten. Wie Sie sagten, gibt es nicht viel Schlimmeres als veraltete Kommentare (genauso schlimm, wenn nicht schlimmer als ausgelassene Dokumente).

Demian Brecht
quelle
10

Gehen wir von der Annahme aus, dass Entwicklerzyklen die Ressource sind, die wir zu schonen versuchen.

Das bedeutet also, dass Entwickler keine Zeit damit verschwenden sollten, selbstverständliche Parameter und Rückgabewerte zu dokumentieren, oder?

Nun, lass es uns aufschlüsseln.

Wenn wir alles dokumentieren, vorausgesetzt, die Randkommentare sind wirklich trivial und erfordern keine Überlegungen oder Nachforschungen, sind die Kosten die zusätzliche Zeit, um den Kommentar tatsächlich einzutippen und Tippfehler zu beheben.

Wenn wir uns entscheiden, sind die Kosten:

  • Den Streit mit den anderen Entwicklern in Ihrem Team führen und gewinnen, die der Meinung sind, dass alles dokumentiert werden sollte.
  • Bestimmen Sie für jeden Parameter, ob dies dokumentiert werden soll oder nicht.
  • Weitere Auseinandersetzungen mit Ihrem Team, wenn jemand anderer Meinung ist, ob ein Parameter hätte dokumentiert werden sollen.
  • Verbringen Sie viel Zeit damit, den Code zu durchsuchen und zu recherchieren, wenn sich herausstellt, dass ein Parameter, der als selbsterklärend eingestuft wurde, dies nicht ist.

Ich wäre also geneigt, einfach alles zu dokumentieren. Der Nachteil ist definitiv, ist aber enthalten.

JohnMcG
quelle
9

Wenn Sie Javadoc trotzdem schreiben, können Sie es genauso gut vollständig schreiben, sogar mit den "offensichtlichen" Parametern. Sie mögen für Sie oder den anderen Entwickler offensichtlich sein, aber jeder, der sie neu betrachtet, würde davon profitieren, die Absicht jedes Parameters zu kennen.

Um Javadoc ordnungsgemäß zu verwalten, müssen Sie Tools für Ihre Entwicklung verwenden, die Ihnen dabei helfen. Eclipse fällt mir ein. Wenn es wichtig ist, müssen Sie natürlich sicherstellen, dass jeder im Team seinen Teil dazu beiträgt, den Code einschließlich der Kommentare zu pflegen.

Bernard
quelle
3

Vergessen Sie nicht, dass Javadoc unabhängig vom Code sichtbar gemacht werden kann, zum Beispiel durch die Java-API . Indem Sie das Javadoc nicht für jeden Parameter in eine Methode aufnehmen, stellen Sie die Methode falsch dar und erklären, wie sie verwendet werden könnte.

Covar
quelle
Fügt "a - das Argument, dessen absoluter Wert bestimmt werden soll" wirklich etwas zur Dokumentation von Math.abs hinzu?
Kevin Cline
@ Kevin Cline könnte nützlich sein für die schwer zu denken ;-)
Gary Rowe
1

'Notwendig' ist völlig subjektiv. Ich denke, was Sie fragen, ist, "in Ihrer Situation, sollten Sie einen Javadoc-Kommentar hinzufügen". Sie kennen weder den Umfang noch den Kontext Ihrer App. Wie können wir wissen, was für Sie geeignet ist?

Wenn dieser öffentlich zugängliche Code (dh Code, auf den andere zugreifen können, z. B. eine API), muss jeder einzelne Parameter dokumentiert werden. Gehen Sie nicht davon aus, dass der Leser so viel über das Projekt weiß wie Sie. Ansonsten liegt es an Ihnen und Ihrem Team, Ihre eigenen Entscheidungen zu treffen.

GroßmeisterB
quelle
6
Ich finde, dass es mir hilft , meinen eigenen Code zu verstehen , wenn ich Jahre später darauf zurückblicke , auch wenn es nicht öffentlich ist : P
Demian Brecht
1
Dieser Ansatz ist auch bekannt als "Mist, wir werden den Neuen dazu bringen, den verdammten Code in 4 Jahren zu lesen, nachdem wir gegangen sind." Ansatz.
Tim Williscroft