Bewährte Methoden für das Schreiben und Dokumentieren von Kommentaren

Das Kommentieren ist heutzutage einfacher als je zuvor. In Java gibt es einige nette Techniken zum Verknüpfen von Kommentaren mit Klassen, und Java IDEs sind gut darin, Kommentar-Shells für Sie zu erstellen. In Sprachen wie Clojure können Sie sogar eine Beschreibung einer Funktion als Argument in den Funktionscode selbst einfügen.

Wir leben jedoch immer noch in einer Zeit, in der es oft veraltete oder schlechte Kommentare von guten Entwicklern gibt. Ich bin daran interessiert, die Robustheit und Nützlichkeit meiner Kommentare zu verbessern.

Insbesondere interessiere ich mich hier für Java / Clojure / Python, aber die Antworten müssen nicht sprachspezifisch sein.

Gibt es neue Techniken, die Kommentare validieren und entweder "schwache" Kommentare (z. B. Kommentare mit magischen Zahlen, unvollständige Sätze usw.) oder falsche Kommentare (z. B. falsch geschriebene Variablen oder ähnliches) automatisch erkennen?

Und was noch wichtiger ist: Gibt es akzeptierte "Kommentar-Richtlinien" oder Strategien? Es gibt viele Ratschläge zum Codieren - aber was ist mit "Wie kommentiere ich?"

• Namen / Unterlagen sollten Ihnen sagen, was Sie tun.

• Die Implementierung sollte Ihnen sagen, wie Sie es tun.

• In den Kommentaren sollten Sie erfahren, warum Sie es so machen, wie Sie es tun.

Dies mag umstritten sein, aber mein Rat wäre, so wenige Kommentare wie möglich zu verfassen. Verwenden Sie stattdessen nette, eindeutige Klassennamen, Variablennamen und Methodennamen. Schreiben Sie Ihren Code so klar wie möglich. und betrachten Sie dies als das wichtigste Attribut Ihres Codes (abgesehen davon, dass es seinen Anforderungen entspricht). Schreiben Sie einen Kommentar nur, wenn Sie eine Methode so klar wie möglich formuliert haben und dennoch der Meinung sind, dass weitere Erläuterungen erforderlich sind.

Und haben eine organisatorische Praxis, dass, wenn jemand eine Klasse in irgendeiner Weise ändert, er sicherstellen muss, dass die Kommentare immer noch alle korrekt sind.

Bei anderen Sprachen bin ich mir nicht sicher, aber mit Python können Sie Doctests schreiben, die eine Form von selbstvalidierenden Kommentaren sind. Natürlich sollten sie nicht anstelle von realen Einheitentests verwendet werden, sondern sind eine schnelle und einfache Methode, um bestimmte Funktionen zu dokumentieren, die möglicherweise nicht so offensichtlich sind, wie sie sein sollten. Sie bieten den zusätzlichen Vorteil, dass Sie die Kommentartests ausführen können, um zu überprüfen, ob die Kommentare noch korrekt sind (zumindest der Teil, der Tests enthält).

Einer der maßgeblichsten Stellen, an denen ermittelt wird, wie Code-Kommentare zum automatischen Generieren von Dokumentation verwendet werden können, ist mit Sicherheit Doxygen . Allerdings könnte es mir mehr solcher Tools geben.

Dies definiert den Standard für das Schreiben von Kommentaren, nach dem die Dokumentation automatisch erstellt werden soll. Dies ist jedoch eher eine Struktur, die jedoch nicht semantisch validiert wird. Zum Beispiel kann es nicht überprüfen, ob Sie irreführendes Englisch verwendet haben, um den Zweck einer Funktion zu beschreiben!

Dies ist zwar das Beste, was Kommentare strukturiert macht, ich persönlich bin jedoch der Meinung, dass mehr Dokumentation erforderlich ist, um den Code als solchen besser pflegbar zu machen. Vor einiger Zeit gab es in P.SE eine Frage. Kann Code die Dokumentation in Open Source-Entwicklertools sein? Wie oft ist es Dies gilt natürlich auch für Nicht-Open-Source-Projekte.

Um den Code wartungsfreundlicher zu machen, ist es praktisch wichtiger, dass eine externe Dokumentation vorhanden ist, mit deren Hilfe eine Struktur für den Umgang mit Code erstellt werden kann. Anschließend sollte die Anzeige von Kommentaren im Code eingeschränkt werden

Ich denke, wenn Sie die Richtlinien für das Schreiben von Kommentaren definieren möchten, sollten Sie dies als ganzheitlichen Ansatz in den Kodierungsstandard aufnehmen. Siehe hierzu: Was können einige Gefahren bei der Einführung einer Software zur Erstellung von Stilrichtlinien und Dokumentationen in einem Entwicklungsteam sein?

Normalerweise macht ein Kommentar weniger als 5% des Codes aus. Und in der Praxis ist es praktisch schwierig, Kommentare zu überprüfen, während Code-Überprüfungen selbst viel weniger Aufmerksamkeit (über andere Aspekte der Entwicklung) auf sich ziehen.

Gibt es neue Techniken, die Kommentare validieren und entweder "schwache" Kommentare (z. B. Kommentare mit magischen Zahlen, unvollständige Sätze usw.) oder falsche Kommentare (z. B. falsch geschriebene Variablen oder ähnliches) automatisch erkennen?

Es gibt eine bekannte Technik - sie heißt "Code-Review" und hat eine Schwester namens "Pair-Programming". Erwarten Sie hier nichts "Automagisches".

Und was noch wichtiger ist: Gibt es akzeptierte "Kommentar-Richtlinien" oder Strategien? Es gibt viele Ratschläge zum Codieren - aber was ist mit "Wie kommentiere ich?"

"Code complete" enthält nicht nur Informationen zum Codieren, sondern auch Kapitel zum Kommentieren, insbesondere zum Schreiben von selbstdokumentierendem Code.

Eine Quelle, die mir besonders gefallen hat, ist Oracle's How to Write Doc Comments für das Javadoc Tool :

In diesem Dokument werden die Style-Guide-, Tag- und Image-Konventionen beschrieben, die wir in Dokumentationskommentaren für Java-Programme verwenden, die bei Java Software, Sun Microsystems, geschrieben wurden.

Und Punkt 44: Schreiben Sie Dokumentkommentare für alle offengelegten API-Elemente :

Wenn eine API verwendet werden soll, muss sie dokumentiert werden. Bisher wurde die API-Dokumentation manuell generiert und mit dem Code synchron gehalten. Die Java-Programmierumgebung erleichtert diese Aufgabe mit dem Javadoc-Dienstprogramm. Javadoc generiert die API-Dokumentation automatisch aus dem Quellcode mit speziell formatierten Dokumentationskommentaren, die üblicherweise als Dokumentationskommentare bezeichnet werden.

aus der Effective Java 2nd Edition .