Code-Pflege: Kommentare in Code einfügen oder einfach der Versionskontrolle überlassen?

42

Wir wurden gebeten, Kommentare mit Start-Tags, End-Tags, Beschreibung, Lösung usw. für jede Änderung hinzuzufügen, die wir im Rahmen der Behebung eines Fehlers / der Implementierung eines CR am Code vornehmen.

Mein Anliegen ist, bietet dies einen Mehrwert? Wie es ist, haben wir alle Details in der Versionskontrollhistorie, die uns helfen werden, jede einzelne Änderung zu verfolgen?

Aber meine Leads bestehen darauf, die Kommentare als "gute" Programmierpraxis zu haben. Eines ihrer Argumente ist, dass es umständlich wäre, wenn ein CR dekontrolliert / geändert werden muss, wenn Kommentare nicht vorhanden wären.

In Anbetracht der Tatsache, dass die Änderungen größtenteils zwischen den einzelnen Codes liegen, ist es dann wirklich hilfreich, zu jeder Änderung, die wir vornehmen, Kommentare hinzuzufügen? Sollten wir es nicht der Versionskontrolle überlassen?

Chillax
quelle

Antworten:

43

Du liegst absolut richtig. Das Nachverfolgen von Änderungen ist die Aufgabe Ihres Versionskontrollsystems. Jedes Mal, wenn Sie ein Commit ausführen, sollten Sie eine Commit-Nachricht schreiben, in der erläutert wird, was getan wurde, und auf Ihr Fehlerverfolgungssystem verweisen, wenn dies eine Fehlerbehebung ist. Fügen Sie einen Kommentar in den Code ein und sagen Sie:

// begin fix for bug XXXXX on 10/9/2012
...
// end fix for bug XXXXX

Jedes Mal, wenn Sie einen Fehler beheben, wird Ihr Code schnell unlesbar und nicht mehr wartbar. Es wird auch dazu führen, dass dieselben Informationen an zwei Stellen dupliziert werden, was das Durcheinander noch verschlimmert.

Kommentare sollten nicht zur Fehlerverfolgung verwendet werden und sie sollten auch nicht beschreiben, was Ihr Code tut. Sie sollten erklären, warum Sie X machen oder warum Sie X auf diese besondere Weise machen. Wenn Sie das Gefühl haben, einen Kommentar schreiben zu müssen, der erklärt, was ein Codeblock tut, ist dies ein Codegeruch, der angibt, dass Sie diesen Block in eine Funktion mit einem beschreibenden Namen umgestalten sollten.

Also statt

// fixed bug XXXXX on 10/9/2012

Möglicherweise haben Sie einen Kommentar, der besagt

// doing X, because otherwise Y will break.

oder

// doing X, because doing Y is 10 times slower.
Dima
quelle
12
+1 für den Code-Geruch von Kommentaren, die "was" erklären. Es ist schön zu sehen, dass Codekommentare kein automatischer Vorteil in dem Sinne sind, dass mehr Kommentare> weniger Kommentare. Ich könnte sogar ein Level zurückziehen und denken, dass es Fälle gibt, in denen sogar Kommentare, die das "Warum" beschreiben, ein Geruch sind, der darauf hinweist, dass der Code nicht klar ist. Wenn ich beispielsweise einen BubbleSorter oder einen QuickSorter injizieren kann, ist der Kommentar "Ich verwende QuickSorter, weil er schneller ist" ebenso überflüssig wie "QuickSorter injizieren". YMMV.
Erik Dietrich
53

Verwenden Sie das beste Werkzeug für den Job. Ihr Versionskontrollsystem sollte das beste Werkzeug für die Aufzeichnung von Bugfixes und CRs sein: Es zeichnet automatisch das Datum auf und wer die Änderung vorgenommen hat. Das Hinzufügen einer Nachricht wird nie vergessen (wenn Sie sie so konfiguriert haben, dass Commit-Nachrichten erforderlich sind). Es kommentiert niemals die falsche Codezeile oder löscht versehentlich einen Kommentar. Und wenn Ihr Versionskontrollsystem bereits bessere Arbeit leistet als Ihre Kommentare, ist es dumm, Arbeit durch Hinzufügen von Kommentaren zu duplizieren.

Die Lesbarkeit des Quellcodes ist von größter Bedeutung. Eine Codebasis, die mit Kommentaren übersät ist, die den vollständigen Verlauf aller gemachten Bugfixes und CRs wiedergeben, wird überhaupt nicht gut lesbar sein.

Aber überspringen Sie Kommentare nicht komplett: Gute Kommentare (die nicht jeden Start / Stopp / Beschreibung / Lösung jedes Bugfixes und jeder CR sklavisch dokumentieren) verbessern die Lesbarkeit des Codes. Wenn Sie beispielsweise einen schwierigen oder unklaren Code zur Behebung eines Fehlers hinzufügen, ist ein Kommentar des Formulars // fix ISSUE#413, mit dem Sie erfahren, wo Sie weitere Informationen in Ihrem Issue-Tracker finden, eine hervorragende Idee.

Josh Kelley
quelle
29
Ich bin damit einverstanden, abgesehen von einer Sache: fix ISSUE#413Ist kein guter Kommentar im Code. Sie sollten in der Lage sein, den Code zu verstehen, ohne auf externe Dokumentation verweisen zu müssen. Erklären Sie, warum dieser knifflige Teil des Codes erforderlich ist, um was zu tun, anstatt eine Zufallszahl anzugeben. Das ist, was Kommentare sind für: Um diejenigen Teile des Codes zu erklären, die nicht offensichtlich sind.
poke
12
@poke - Vielen Dank, dass Sie darauf hingewiesen haben. Ich denke, ich sollte hinzufügen, dass der einzige Ort, an dem ich Kommentare des Formulars verwende, der Ort fix ISSUE#413ist, an dem das Problem so kompliziert ist (ein extrem betriebssystem- und konfigurationsabhängiger Eckfall oder nur ausgelöst durch bestimmte schlechte Kundendaten), dass eine angemessene Beschreibung erforderlich ist paar Absätze; So etwas wird besser von einem Issue-Tracker, IMO, erledigt. Selbst dann ist eine kurze Beschreibung gut.
Josh Kelley
8
@poke: Ich würde sagen, dass ein Kommentar, der mit beginnt, fix ISSUE#413 vollkommen in Ordnung und sogar vorzuziehen ist, solange er auch eine angemessene Menge an Informationen darüber enthält, um welches Problem es sich bei # 413 handelt. Die bloße Zusammenfassung des Problemberichts ohne einen Hinweis darauf erschwert einem zukünftigen Leser, der alle Details benötigt, das Leben.
Keith Thompson
Ich bin mit Poke einverstanden - Sie sollten niemals auf eine externe Quelle verweisen müssen, um den Code zu verstehen. Wenn ich eine Änderung überprüfe, wird der Fluss unterbrochen. Ich muss zum Issue Tracker gehen, das Thema aufgreifen und alles darüber lesen. Und was passiert, wenn Sie den Issue Tracker wechseln? Der fix ISSUE#413Vollständigkeit halber mag es in Ordnung sein, einen Kommentar abzugeben, aber verwenden Sie ihn nicht als Krücke.
Michael Dean
"Es wird nie vergessen, eine Nachricht hinzuzufügen (wenn Sie es so konfiguriert haben, dass Commit-Nachrichten erforderlich sind). Es wird niemals die falsche Codezeile mit Anmerkungen versehen oder versehentlich ein Kommentar gelöscht." Wir haben uns gerade mit SVN befasst, das sich selbst beschädigt und von einem Backup wiederherstellen muss. Wir konnten Code finden, der es noch nicht zum Sichern geschafft hat, aber wenn wir die Änderungen erneut festschreiben, werden mehrere separate Festschreibungen zu einer. Mein Punkt ist niemals ein zu starkes Wort, und wir dürfen nicht vergessen, dass Leute auf eine neue VCS-Software umsteigen, und dass das Einspielen des Revisionsverlaufs möglicherweise nicht machbar oder möglich ist.
Andy
7

Kommentare im Code sind über das, was der Code ist in diesem Moment. Das Erstellen eines Schnappschusses zu einem bestimmten Zeitpunkt sollte sich nicht auf alte (oder noch schlimmer zukünftige) Versionen des Codes beziehen.

In VCS-Kommentaren wird erläutert, wie sich der Code geändert hat. Sie sollten als eine Geschichte über die Entwicklung lesen.

Jetzt sollte jede Änderung Kommentare enthalten? in den meisten Fällen ja. Die einzige Ausnahme, die ich mir vorstelle, ist, wenn das erwartete Verhalten bereits dokumentiert wurde, aber aufgrund eines Fehlers nicht das war, was Sie hatten. Durch die Korrektur werden die vorhandenen Kommentare präziser, sodass sie nicht geändert werden müssen. Der Fehler selbst sollte im Ticketverlauf und im Festschreibungskommentar dokumentiert werden, jedoch nur im Code, wenn der Code seltsam aussieht. In diesem Fall // make sure <bad thing> doesn't happensollte a ausreichen.

Javier
quelle
8
Ich würde dem zustimmen, aber ich kann nicht wirklich zustimmen, dass "jede Änderung Kommentare enthalten sollte? In den meisten Fällen ja". Ein Check-In / Commit Kommentar, ja, absolut. Codekommentare, definitiv nicht unbedingt.
ein CVn
6

Eine Art von Kommentar, den ich sehr schätze, ist:

// Dies wurde für Geschäftsregel 5 von Vorschlag 2 implementiert

oder was auch immer zum Teufel Sie verwenden, um Ihre Anforderungen zu sammeln.

Dies hat zwei Vorteile: Zum einen können Sie feststellen, warum Sie einen bestimmten Algorithmus ohne Suchen implementiert haben, und zum anderen können Sie mit Nicht-Software-Ingenieuren kommunizieren, die an den Anforderungsdokumenten arbeiten bzw. diese erstellen.

Dies hilft vielleicht nicht bei kleineren Teams, aber wenn Sie Analysisten haben, die Ihre Anforderungen entwickeln, kann dies von unschätzbarem Wert sein.

Bill K
quelle
2
Dies ist jedoch anders, da dies eine Rückverfolgbarkeit bietet, die orthogonal zur Versionskontrolle ist: die Verbindung zwischen dem Code und der von ihm implementierten Anforderungsspezifikation.
Kaz
In einem System, in dem die Versionskontrolle mit dem Fehler- / Anforderungssystem gekoppelt ist, ist die vollständige Rückverfolgbarkeit ohne Kommentar gewährleistet. Manchmal ist es hilfreich, in die andere Richtung zu arbeiten. Zeigen Sie mir anhand einer SCM-Datei, welche Anforderungen wann implementiert wurden. Oder zeigen Sie mir bei einer bestimmten Anforderung alle Dateien, die zur Implementierung geändert wurden.
10.
4

Ihre Leads haben Recht, wenn sie sagen, dass Kommentare eine gute Programmierpraxis sind, es gibt jedoch Ausnahmen. Das Hinzufügen eines Kommentars für jede Änderung, die Sie vornehmen, ist eine davon. Und Sie haben Recht, wenn Sie sagen, dass dies zum Versionskontrollsystem gehören sollte. Wenn Sie diese Kommentare an einem einzigen Ort aufbewahren müssen, ist das VCS der richtige Weg. Kommentare im Quellcode werden in der Regel alt und nicht mehr gepflegt. Keine Kommentare sind viel besser als schlechte Kommentare. Was Sie nicht wollen, sind Kommentare an beiden Stellen (im Code und im VCS), die nicht synchron sind. Das Ziel ist es, die Dinge trocken zu halten, indem eine einzige Quelle der Wahrheit für Änderungen am Code zur Verfügung steht.

Marco-Fiset
quelle
3

Überlegen Sie sich zusätzlich zu den Aussagen anderer, was passiert, wenn eine Änderung Auswirkungen auf das gesamte System hat. Angenommen, Sie überarbeiten einen Teil einer Kernschnittstelle beim Implementieren einer Änderungsanforderung - diese Art von Änderung kann leicht einen großen Prozentsatz der Quellcodedateien in jeder nicht trivialen Software mit geringfügigen Änderungen (Klasse oder Klasse) berühren Änderungen des Methodennamens). Sollen Sie jede einzelne Datei durchgehen, die von einer solchen Operation betroffen ist, um sie manuell mit solchen Kommentaren zu versehen, anstatt sich darauf zu verlassen, dass das VCS alles automatisch erledigt? In einem Fall benötigen Sie mit einem anständigen Refactoring-Tool nur wenig mehr als fünf Minuten, gefolgt von einer Neukompilierung, um sicherzustellen, dass der Build nicht beschädigt wurde, während der andere Job leicht zu einer Tagesaufgabe werden kann. Zu welchem ​​spezifischen Nutzen?

Überlegen Sie auch, was passiert, wenn Sie Teile des Codes verschieben. Einer der Datenbankentwickler, mit denen ich zusammenarbeite, ist im Lager der "Großteils". Jede SQL-Zeile sollte mit der Revision, in der sie geändert wurde, kommentiert werden, und wir werden für jede Datei separate Revisionsverläufe erstellen, da dies einfacher zu sehen ist wer hat was wann und warum geändert ". Das funktioniert irgendwie in Ordnung, wenn die Änderung istin der Reihenfolge der Änderung einzelner Zeilen. Es funktioniert nicht ganz so gut, wenn Sie, wie ich es kürzlich getan habe, um ein schwerwiegendes Leistungsproblem zu beheben, Teile einer größeren Abfrage herausbrechen, indem Sie temporäre Tabellen einführen, und dann die Reihenfolge einiger Abfragen ändern, um sie besser an den neuen Codefluss anzupassen. Zugegeben, der Unterschied zur Vorgängerversion war weitgehend bedeutungslos, da ungefähr zwei Drittel der Datei geändert wurden, aber der Eincheckkommentar war auch so etwas wie "Umstrukturierung zur Behebung von Leistungsproblemen". Als Sie die beiden Versionen manuell betrachteten, war ziemlich klar, dass große Teile wirklich gleich waren und sich nur bewegten. (Die Ausführung der betreffenden gespeicherten Prozedur dauerte regelmäßig mehr als eine halbe Minute bis zu einigen Sekunden. Zu diesem Zeitpunkt

Mit sehr wenigen Ausnahmen ist das Verfolgen von Änderungen und das Referenzieren von Problemen die Arbeit des VCS, IMNSHO.

ein CVn
quelle
3

Ich halte mich normalerweise an diese Regel: Wenn die Änderung offensichtlich ist und der resultierende Code keine Fragen aufwirft, kein vorheriges Verhalten in erheblicher Weise rückgängig macht oder wesentlich ändert, überlasse es dem VCS, die Fehlernummern und andere Änderungsinformationen zu verfolgen.

Wenn es jedoch eine Änderung gibt, die nicht offensichtlich ist, die die Logik ändert - insbesondere die Logik, die von jemand anderem auf nicht offensichtliche Weise durchgeführt wird -, kann es sehr vorteilhaft sein, etwas wie "diese Änderung ist dies zu tun und" hinzuzufügen dass wegen Fehler # 42742 ". Auf diese Weise hat jemand, der sich den Code ansieht und fragt: "Warum ist das hier? Das sieht komisch aus?", Eine Anleitung vor Augen und muss keine Untersuchung über VCS durchführen. Dies verhindert auch Situationen, in denen andere Benutzer die Änderungen nicht mehr durchführen können, da sie mit dem alten Status des Codes vertraut sind, ihn jedoch seitdem nicht mehr geändert haben.

STASM
quelle
2

Versionskontrollbezogene Kommentare gehören nicht in die Quelldatei. Sie fügen nur Unordnung hinzu. Da sie wahrscheinlich an derselben Stelle abgelegt werden müssen (wie ein Kommentarblock oben in der Datei), verursachen sie beim Zusammenführen von parallelen Zweigen nur Kommentare.

Tracking-Informationen, die der Versionskontrolle entzogen werden können, sollten nicht im Hauptteil des Codes dupliziert werden. Das gilt für alberne Ideen wie die RCS-Checkout-Schlüsselwörter $Log$und ihre Besonderheiten.

Wenn sich der Code jemals außerhalb des Bereichs des Versionskontrollsystems bewegt, verliert diese Spur von Kommentaren zu seinem Verlauf den Kontext und damit den größten Teil seines Werts. Um die Beschreibung der Änderung richtig zu verstehen, benötigen wir Zugriff auf die Revision, damit wir den Unterschied zur vorherigen Version anzeigen können.

Einige alte Dateien im Linux-Kernel haben große History-Kommentarblöcke. Diese stammen aus der Zeit, als es noch kein Versionskontrollsystem gab, sondern nur Tarballs und Patches.

Kaz
quelle
2

Kommentare im Code sollten minimal und genau sein. Hinzufügen von Fehler- / Änderungsinformationen nicht wertvoll. Sie sollten dafür die Versionskontrolle verwenden. Manchmal bietet die Versionskontrolle eine etwas bessere Möglichkeit, Änderungen vorzunehmen. Wir verwenden ClearCase UCM. UCM-Aktivitäten werden basierend auf Fehlernummern, Änderungsbereich usw. erstellt (z. B. defect29844_change_sql_to_handle_null).

Detaillierte Kommentare werden in den Check-in-Kommentaren bevorzugt.

Ich bevorzuge es, Details zu Hintergrundinformationen anzugeben, Details zu der Lösung, die aufgrund einiger Nebenwirkungen NICHT implementiert wurde.

Pramagic Programmer und CleanCode führen zu folgenden Richtlinien

Behalten Sie das Wissen auf niedriger Ebene in dem Code bei, zu dem es gehört, und behalten Sie die Kommentare für andere Erklärungen auf hoher Ebene vor.

Jayan
quelle