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

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?

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.

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.

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.

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.

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.

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

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.

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.

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.