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

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.

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

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

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.

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.

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.

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