Anfängerleitfaden zum Schreiben von Kommentaren?

27

Gibt es eine definitive Anleitung zum Schreiben von Code-Kommentaren für angehende Entwickler?

Im Idealfall geht es darum, wann Kommentare verwendet werden sollten (und welche nicht) und welche Kommentare enthalten sollten.

Diese Antwort :

Kommentieren Sie nicht, WAS Sie tun, sondern WARUM Sie es tun.

Das WAS wird durch sauberen, lesbaren und einfachen Code mit der richtigen Auswahl von Variablennamen erledigt, um dies zu unterstützen. Kommentare weisen eine übergeordnete Struktur für den Code auf, die vom Code selbst nicht (oder nur schwer) angezeigt werden kann.

kommt dem nahe, ist aber für unerfahrene Programmierer etwas prägnant (eine Erweiterung mit mehreren Beispielen und Eckfällen wäre meiner Meinung nach hervorragend).

Update : Zusätzlich zu den Antworten hier halte ich diese Antwort auf eine andere Frage für äußerst relevant.

language-agnostic comments Cameron
quelle
Ich denke, wir bewegen uns schnell in eine Welt, in der die Leute keine Kommentare mehr abgeben. Zum Besseren oder (eher) zum Schlechten. Agil.
MK01
1
@MK: Wenn das der Fall ist (ich stimme dieser Antwort eher zu ), wäre eine Anleitung, die erklärt, wie man keine Kommentare schreibt und warum sie vermieden werden sollten, genauso nützlich. Tatsächlich ist es umso besser, je mehr unterschiedliche Standpunkte vertreten werden.
Cameron
Ich halte kleine Kommentare zur Verbesserung der Lesegeschwindigkeit für sehr hilfreich und werde es immer sein. Ich kann die Argumentation des "veralteten Kommentars" nicht voll und ganz akzeptieren, selbst wenn sie veraltet wären, hätten sie einen historischen Wert. Ich arbeitete an einer Codebasis, die gelegentlich detaillierte Kommentare enthielt, und war nie wirklich gebissen von dem Problem, dass der Kommentar veraltet war.
MK01
siehe auch: "Kommentare sind ein Code-Geruch"
Mücke

Antworten:

38

Sie sollten sich der größten Schwäche von Kommentaren bewusst sein: Sie werden abgestanden. Das heißt, wenn sich der Code ändert, aktualisieren Entwickler Kommentare selten, um mit dem Code synchron zu bleiben. Das bedeutet, dass Sie ihnen niemals vertrauen können und trotzdem den Code lesen. Aus diesem Grund sollte Ihr Code selbstdokumentierend sein. Sie sollten Ihre Funktions- und Variablennamen so wählen, dass der Code wie eine Prosa liest.

Dokumentieren Sie also nicht, WAS der Code tut. Selbstdokumentierender Code sollte sich darum kümmern. Dokumentieren Sie, WARUM Sie es tun. Die WARUMs beziehen sich normalerweise auf Geschäftsregeln oder auf die Architektur und ändern sich nicht oft und veralten bei den WARUMs nicht so schnell. Dokumentenkantenfälle. Dokumentausnahmen. Entscheidungen zum Dokumentendesign. Dokumentieren Sie vor allem die Entwurfsentscheidungen, die Sie berücksichtigt, aber nicht umgesetzt haben (und dokumentieren Sie, WARUM Sie sich gegen die Verwendung entschieden haben).


quelle
2
Der letzte ist sehr wichtig. Manchmal gibt es einen Fehler / Nebeneffekt bei der Implementierung der offensichtlichen Lösung. Die Dokumentation, warum Sie sich für eine andere Lösung entschieden haben, verhindert, dass der nächste Entwickler den Fehler erneut einführt, wenn er Ihre scheinbar schlechte Lösung "repariert".
CaffGeek
2
Ein weiterer Punkt, mein erster Job betrachtete Kommentare als so wichtig wie Code. Machen Sie es sich zur Gewohnheit, beim Peer-Review sowohl Kommentare als auch den Code zu lesen, und bestehen Sie darauf, dass die Kommentare nach Möglichkeit auf dem neuesten Stand sind. Dies hilft zu vermeiden, dass die Kommentare veralten, und hält die Geschäftsregeln usw., die in Ihrem Code dokumentiert sind, auf dem neuesten Stand.
Eric Hydrick
10

Sie sollten Robert C. Martins Clean Code- Buch lesen . Es erklärt gut, dass Sie wahrscheinlich nicht richtig codieren, wenn Sie Kommentare benötigen. Im Idealfall sollte Ihr Code "selbstkommentierend" sein. Das Clean Coder-Buch erklärt, wie dies getan wird, sodass Kommentare nicht erforderlich sind, und es beschreibt, wie Kommentare in Situationen ausgeführt werden, in denen dies erforderlich ist. (Wie das Erläutern einer komplexen mathematischen Formel)

Bob
quelle
Obwohl ich würde eine komplexe mathematische Formel nicht so sehr wollen , erklärte , wie ich es möchte , geschrieben in der richtigen mathematischer Notation (möglicherweise TeX), mit einer Erklärung seiner Bedeutung und Quelle. Wenn Sie die Formel nicht verstehen, sollten Sie nicht mit dem Code herumspielen, der sie verwendet, um einen Wert zu berechnen, da Sie höchstwahrscheinlich Fehler verursachen (subtile oder nicht).
ein Lebenslauf vom
Code kann nur sagen wie , nicht warum oder warum nicht . Du brauchst Kommentare dazu.
7

Wie bereits erwähnt, enthält Code Complete verschiedene Richtlinien zum Schreiben von Kommentaren. Kurz gesagt, es ist PDL und kann wie folgt zusammengefasst werden:

  1. Beschreiben Sie Ihre Absicht, nicht was der Code tut. Vermeiden Sie es, Implementierungsdetails zu beschreiben, es sei denn, Sie verwenden einen Trick oder benutzerdefinierte Implementierungen. Beispiel: Verwenden von Bitverschiebungen zum Teilen, Verwenden von Zeigerarithmetik für den Zugriff auf Klassenmitglieder oder Verwenden eines benutzerdefinierten Speicherzuordners für einige Poolobjekte.

  2. Schreiben Sie zuerst den Pseudocode (dh die Kommentare) und dann den Code in real, nachdem Sie Ihre Routine / Methode / Funktion beschrieben haben. Die verwendete Sprache ist auf hohem Niveau und dennoch spezifisch, sodass sie ziemlich ausführlich sein kann

  3. Machen Sie sich schon vor dem Schreiben des Codes ein Bild von der Funktionsweise Ihres Codes

  4. Habe Kommentare so nah wie möglich am eigentlichen Code

Das Ziel ist es, langwierige, nicht verwandte Kommentare zu vermeiden, die möglicherweise veraltet sind, aber Kommentare zu haben, die die Absicht und den Zweck des Codes widerspiegeln. Die Verwendung eines Pseudocodes auf hoher Ebene hilft auch dabei, Ihre Überlegungen zu klären, bevor Sie die Implementierung schreiben.

Auf GameDev.net gibt es einen Link [der PDL erklärt] [1], falls Sie das Buch nicht aufspüren möchten.

Extrakun
quelle
5
Schreiben Sie zuerst den Pseudocode (dh die Kommentare) . Ich konnte nicht mehr widersprechen. Es gibt keinen besseren Weg, um sicherzustellen, dass Kommentare nicht mit dem Code übereinstimmen. Neue Codierer (und der Fragesteller, der speziell um eine Anleitung für Anfänger gebeten wurde) hacken und überarbeiten Funktionen hundertmal, bevor sie damit zufrieden sind habe eine elegante funktionierende Lösung, aber es wird nichts wie ihr anfänglicher Pseudocode aussehen. Werden die Kommentare verschoben und aktualisiert, sobald der Code funktioniert? Sie können darauf wetten, dass Ihr süßer Hippie es nicht tut. Meine zwei Cent.
Binary Worrier
1
Pseudocode-Kommentare zeigen Ihnen auch, was der Code tun soll. Der Code sollte Ihnen das sagen. Pseudocode sagt Ihnen nicht, warum der Code dies tut. -1 Alter, sorry, aber ich kann dem zweiten Punkt nicht zustimmen, die Zeiten haben sich geändert.
Binary Worrier
1
Nicht zu streiten, sondern eher zu erklären - der Pseudocode erklärt die Absicht des Codes, den Sie geschrieben haben. Das heißt, der Kommentar handelt nicht von Implementierungsdetails (z. B. "Add x to the top of the stack"), sondern davon, was der Code tun soll (z. B. "Das Fenster vor allem anderen anzeigen"). Wie Sie zu Recht betont haben, müssen Sie Kommentare mit dem Code verschieben. Ich bin nicht einverstanden mit dem Code kann Ihnen sagen, was der Code tut - die ganze Zeit. Auch wenn ein hilfreicher / genauer Kommentar (wenn ich es schaffe, ihn gut zu schreiben!) Einen langen Weg zurücklegt. Am Ende noch IMHO.
Extrakun
3
Eine aufgerufene Methode oder Funktion showWindowOnTop(window)ist immer besser als ein Kommentar der gleichen Art. All dies ist veraltet und im Jahr 2012 nicht mehr empfohlen. Tests sagen Ihnen, was der Code tun soll, bevor Sie ihn schreiben. 4) Gut benannter Code ist besser als Kommentare, die nicht mit schlecht benanntem Code
1

Mein Vorschlag wäre, Code ohne irgendwelche Kommentare zu schreiben und ihn dann zu verlassen. Kommen Sie in einem Jahr darauf zurück und lesen Sie es. Der Teil, den Sie nicht leicht verstehen, ist der Teil, den Sie kommentieren sollten.

Kevin
quelle
1
Hah, ja ;-) Dies ist jedoch kein besonders hilfreicher Rat - vielleicht hätte dies ein Kommentar sein sollen?
Cameron
den Teil, den Sie nicht verstehen, sollten Sie in kleineren, besser benannten Teilen geschrieben haben. Der Hauptgrund, warum Kommentare in den Code eingefügt werden, ist, dass Funktionen / Methoden viel zu lang sind und viele kleinere selbstdokumentierende Teile sein sollten.
0

Es gefällt mir sehr, wie Evan Todd seine Meinung zu den einzig nützlichen Kommentarkategorien zusammenfasst ( zitiert aus seinem Blog ):

  • Kommentare, die erklären, warum und nicht was. Dies sind die nützlichsten.
  • Kommentare mit ein paar Worten, die erklären, was der folgende riesige Codeabschnitt tut. Diese sind nützlich zum Navigieren und Lesen.
  • Kommentare in der Deklaration einer Datenstruktur, die erläutern, was jedes Feld bedeutet. Diese sind oft unnötig, aber manchmal ist es nicht möglich, ein Konzept intuitiv auf den Speicher abzubilden, und Kommentare sind erforderlich, um die Zuordnung zu beschreiben.
Cameron
quelle