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

20

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?"

— jayunit100
quelle

40

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.

— Ratschenfreak
quelle

6

In den Kommentaren sollte auch angegeben werden, warum Sie es nicht anders machen - dh wichtige Entwurfsentscheidungen -, da zukünftige Betreuer diese Informationen ansonsten nicht erhalten.

2

Ich glaube, es gibt viele Male, in denen ein Kommentar sagen sollte, WAS Sie auch tun. Diese Idee, nur "warum" zu kommentieren, ist meiner Meinung nach ein Anti-Muster. Es ist ein Mythos, dass Sie den gesamten Code so klar schreiben können, dass jeder Programmierer ihn auf einen Blick verstehen kann, und meiner Erfahrung nach glauben die meisten Programmierer, dass sie sauberen Code schreiben, dies nicht. Es ist das gleiche wie zu sagen: "Ich muss diese Funktion nicht beschreibend benennen, weil jeder den Code in der Funktion lesen kann, um zu sehen, was sie tut." - das macht doch auch keinen sinn, oder?

— Dallas

2

@dallin wenn dein Code nicht klar ist, was er tut; Betrachten Sie die Umgestaltung. Ansonsten fügen Sie einen Kommentar hinzu, der erklärt, warum es so implementiert ist (was auch das Wie besser erklärt). Ihr Vergleich mit beschreibenden Namen lautet Äpfel / Orangen, ein beschreibender Name verdeutlicht, wo die Funktion verwendet wird , und Sie haben möglicherweise keinen Zugriff auf den Quellcode der Funktion.

— Ratschenfreak

@dallin: "Es ist ein Mythos, dass Sie den gesamten Code so klar schreiben können, dass jeder Programmierer ihn auf einen Blick verstehen kann", möchte Onkel Bob ein Wort mit Ihnen haben. - "Ich muss diese Funktion nicht beschreibend benennen, weil jeder den Code in der Funktion lesen kann, um zu sehen, was sie tut." Um Variablen und Methoden einen guten und eindeutigen Namen zu geben, sollten Programmierer genau angeben, welchen Code sie haben macht gerade!

— klaar

14

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.

— Laut Dawood soll Monica wieder eingesetzt werden
quelle

1

Dies ist ein guter Anfang, aber ich denke, um die Frage des OP zu beantworten, müssen Sie etwas schreiben, das seine tatsächlichen Bedenken in Bezug auf die automatische Validierung anspricht.

— Robert Harvey

2

+1 - Ich denke auch, dass Kommentare nur verwendet werden sollten, um zu erklären, warum Code geschrieben wurde. Ich weiß, was if (a == b) then c();tut, aber wenn ich nicht weiß, warum es das tut - dann sollte ein Kommentar verwendet werden :)

— Deco

Deko - da stimme ich voll zu. Kommentare sind gut, wenn ich verstehen möchte, wie sich eine bestimmte Methode in den gesamten Prozess einfügt. Mit anderen Worten, WARUM Sie diese Methode aufrufen würden oder WARUM sie das tut, was sie tut.

— Dawood sagt, Monica

Wir sollten nicht nur den geschriebenen Code klarstellen, sondern auch sicherstellen, dass Ideen, Gedanken usw. (auf Code-Ebene) mithilfe von TODO-Kommentaren erhalten bleiben. Wenn beispielsweise eine Funktion / Klasse in der Lage ist, die aktuelle Datengröße ordnungsgemäß zu verarbeiten, die Last jedoch möglicherweise nach 2 Jahren nicht mehr verarbeitet wird, schreiben Sie Ihre Beobachtung dort mit dem TODO-Kommentar. Zukünftige Entwickler werden Ihre Bemühungen in der Tat zu schätzen wissen. Versuchen Sie niemals, diese Dinge in einem separaten txt / word-Dokument festzuhalten, während Sie Code schreiben, bezieht sich niemand wirklich auf solche Dokumente.

— TechCoze

siehe auch: "Kommentare sind ein Code-Geruch"

— Mücke

5

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

— Josh Smeaton
quelle

1

Und Sphinx vergleicht den Code mit der Dokumentation, um Kennzahlen zur Abdeckung bereitzustellen.

— S.Lott

3

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.

— Dipan Mehta
quelle

1

Ich bin mit dem letzten Satz hier nicht einverstanden. Ich habe gerade einen Vertrag abgeschlossen und unter einem Teamleiter gearbeitet, der sehr detaillierte Bewertungen abgegeben hat. Seine Reviews enthielten immer die Kommentare - wie sie formuliert wurden, ob die Variablennamen korrekt waren, ob sie alle Informationen enthielten, die ein zukünftiger Entwickler wissen möchte. Es dauerte nicht lange, und ich wusste, was er in jedem Kommentar erwartete, und konnte Kommentare zu seinem Standard erstellen. Vorausgesetzt, es ist eine organisatorische Richtlinie, Codeüberprüfungen durchzuführen und Kommentare in die Codeüberprüfung einzuschließen, geschieht dies.

— Laut Dawood wird Monica

Dies ist normalerweise die einzige Art von Kommentar, die ich schreibe, insbesondere für Methoden, mit denen dokumentiert wird, was eingegeben und was ausgegeben wird (ich arbeite mit lose geschriebenen Sprachen).

— DanMan

2

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.

— Doc Brown
quelle

+1 für Code abgeschlossen. Clean Code von Robert Martin enthält auch ein gutes Kapitel zum Schreiben nützlicher Empfehlungen. Ich bin mir in Bezug auf die Java-Welt nicht sicher, aber in der .NET-Welt gibt es Resharper, mit dem Verweise auf

— Codeelemente

0

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 .

— EGHM
quelle