Sind "bearbeitet von" Inline-Kommentare die Norm in Shops, die die Revisionskontrolle verwenden?


17

Der leitende Entwickler in unserem Shop besteht darauf, dass der zuständige Programmierer bei jeder Änderung des Codes einen Inline-Kommentar hinzufügt, der angibt, was er getan hat. Diese Kommentare sehen normalerweise so aus// YYYY-MM-DD <User ID> Added this IF block per bug 1234.

Wir verwenden TFS zur Versionskontrolle, und es scheint mir, dass Kommentare dieser Art eher als Check-in-Notizen als als Inline-Rauschen geeignet sind. Mit TFS können Sie das Einchecken sogar mit einem oder mehreren Fehlern verknüpfen. Einige unserer älteren, häufig geänderten Klassendateien haben ein Kommentar-zu-LOC-Verhältnis von nahezu 1: 1. Für mich erschweren diese Kommentare das Lesen des Codes und das Hinzufügen von Nullwerten.

Ist dies eine Standardpraxis (oder zumindest eine gängige Praxis) in anderen Geschäften?


12
Ich würde Ihnen zustimmen, dafür sind Revisionsprotokolle in der Versionskontrolle gedacht.
TZHX

1
Der leitende Entwickler in Ihrem Team hat dies getan, bevor die Versionskontrolle weit verbreitet war, und ist nicht zu der Erkenntnis gelangt, dass es woanders hingehört, um den Codegeruch zu entfernen. Zeigen Sie ihm sechs Open-Source-Projekte, die ein Bugzilla- und ein VC-System verwenden, und fragen Sie ihn, ob er in den Kommentaren der jQuery-Bibliothek wissen muss, dass $ .ajax () vor 4 Monaten von jaubourg geändert wurde, und alle geringfügigen Änderungen dazu gehören auch die von hunderten von menschen gemachten. Die gesamte jQuery-Bibliothek wäre ein Durcheinander von Kommentaren, und es wurde nichts gewonnen!
Inkognito

1
Wir haben tatsächlich eine ungeschriebene Richtlinie ohne Namen im Quellcode, da dies zu einem Gefühl der Code-Inhaberschaft führen kann, das als BadThing TM angesehen wird.
Stephen Paulger

Antworten:


23

Normalerweise halte ich solche Kommentare für eine schlechte Praxis, und ich denke, diese Art von Informationen gehört zu den SCM-Festschreibungsprotokollen. In den meisten Fällen ist der Code nur schwerer zu lesen.

Ich mache jedoch immer noch oft so etwas für bestimmte Arten von Bearbeitungen.

Fall 1 - Aufgaben

Wenn Sie eine IDE wie Eclipse, Netbeans oder Visual Studio verwenden (oder eine andere Möglichkeit zur Textsuche in Ihrer Codebasis haben), verwendet Ihr Team möglicherweise bestimmte "Kommentar-Tags" oder "Task-Tags". In diesem Fall kann dies hilfreich sein.

Ich habe von Zeit zu Zeit beim Überprüfen des Codes Folgendes hinzugefügt:

// TOREVIEW: [2010-12-09 haylem] marking this for review because blablabla

oder:

// FIXME: [2010-12-09 haylem] marking this for review because blablabla

Ich verwende dafür verschiedene benutzerdefinierte Task-Tags, die ich in Eclipse in der Task-Ansicht sehen kann, da es eine gute Sache ist, etwas in den Commit-Protokollen zu haben, aber nicht genug, wenn Sie von einer Führungskraft in einem Review-Meeting gefragt werden, warum Bugfix XY vollständig vergessen wurde und schlüpfte durch. Bei dringenden Angelegenheiten oder wirklich fragwürdigen Codeteilen dient dies als zusätzliche Erinnerung (aber normalerweise werde ich den Kommentar kurz halten und die Commit-Protokolle überprüfen, da DIESES der Grund ist, weshalb die Erinnerung hier ist, damit ich den Code nicht überfülle viel).

Fall 2 - Libs-Patches von Drittanbietern

Wenn mein Produkt einen Code von Drittanbietern als Quelle (oder Bibliothek) packen muss, der jedoch aus der Quelle neu erstellt wurde, weil er aus irgendeinem Grund gepatcht werden musste, dokumentieren wir den Patch in einem separaten Dokument, in dem wir diese "Vorbehalte" auflisten. Der Quellcode enthält normalerweise einen Kommentar ähnlich dem folgenden:

// [PATCH_START:product_name]
//  ... real code here ...
// [PATCH_END:product_name]

Fall 3 - Nicht offensichtliche Korrekturen

Dieser ist ein bisschen kontroverser und kommt dem, wonach Ihr Senior-Entwickler fragt, näher.

In dem Produkt, an dem ich gerade arbeite, haben wir manchmal (definitiv keine gemeinsame Sache) einen Kommentar wie:

// BUGFIX: [2010-12-09 haylem] fix for BUG_ID-XYZ

Wir tun dies nur, wenn der Bugfix nicht offensichtlich ist und der Code nicht normal liest. Dies kann zum Beispiel bei Browser-Macken der Fall sein oder obskuren CSS-Korrekturen, die Sie nur implementieren müssen, weil ein Dokumentfehler in einem Produkt vorliegt. Im Allgemeinen würden wir es also mit unserem internen Issue-Repository verknüpfen, das dann die ausführliche Begründung für den Bugfix und Verweise auf die Dokumentation des Fehlers des externen Produkts enthält (z. B. eine Sicherheitsempfehlung für einen bekannten Internet Explorer 6-Fehler) sowas in der Art).

Aber wie gesagt, ist es ziemlich selten. Und dank der Task-Tags können wir diese regelmäßig durchgehen und prüfen, ob diese seltsamen Korrekturen noch Sinn machen oder auslaufen können (zum Beispiel, wenn wir den Support für das fehlerhafte Produkt eingestellt haben, das den Fehler verursacht hat).


Dies nur in: Ein reales Beispiel

In manchen Fällen ist es besser als gar nichts :)

Ich bin gerade auf eine riesige statistische Berechnungsklasse in meiner Codebasis gestoßen, in der der Kopfzeilenkommentar in Form eines Änderungsprotokolls mit der üblichen yadda yadda lautete: Prüfer, Datum, Fehler-ID.

Zuerst dachte ich an das Verschrotten, aber ich bemerkte, dass die Fehler-IDs nicht nur nicht der Konvention unseres aktuellen Issue-Trackers entsprachen, sondern auch nicht derjenigen des Trackers, der vor meinem Eintritt in das Unternehmen verwendet wurde. Also habe ich versucht, den Code durchzulesen und zu verstehen, was die Klasse tat (kein Statistiker), und ich habe auch versucht, diese Fehlerberichte aufzuspüren. Zufälligerweise waren sie ziemlich wichtig und hätten das Leben des nächsten Mannes für die Bearbeitung der Datei gefordert, ohne dass er etwas über sie gewusst hätte, da es sich um geringfügige Präzisionsprobleme und Sonderfälle handelte, die auf sehr spezifischen Anforderungen des ursprünglichen Kunden beruhten . Fazit, wenn diese nicht da gewesen wären, hätte ich es nicht gewusst. Wenn sie nicht dort gewesen wären UND ich die Klasse besser verstanden hätte,

Manchmal ist es schwierig, sehr alte Anforderungen wie diese im Auge zu behalten. Am Ende habe ich immer noch den Header entfernt, aber nachdem ich einen Blockkommentar vor jeder belastenden Funktion eingefügt hatte, der beschreibt, warum diese "seltsamen" Berechnungen spezifische Anforderungen sind.

In diesem Fall hielt ich das immer noch für eine schlechte Praxis, aber ich war froh, dass der ursprüngliche Entwickler sie zumindest eingebaut hat! Wäre besser gewesen, den Code klar zu kommentieren, aber ich denke, das war besser als nichts.


Diese Situationen sind sinnvoll. Danke für die Eingabe.
Joshua Smith

Der zweite Fall ist ein normaler Codekommentar, warum der Code einen Patch enthält. Der erste Fall ist ein gültiger: Nur eine Bemerkung, dass der Code noch nicht fertig ist oder dass an diesem Teil noch etwas zu tun ist.
Salandur

Nun, der leitende Entwickler an meinem Arbeitsplatz (ich) sagt, Änderungen gehen in die Festschreibungskommentare Ihres Softwarekonfigurations-Managementsystems ein. Sie haben Ihr SCM und Ihre Defekt-Tracker miteinander verbunden, oder? (google SCMBUG) Mach nicht manuell, was automatisiert werden kann.
Tim Williscroft

@ Tim: Nun, ich stimme dir zu, wie die erste Zeile der Antwort sagt. Aber in nicht offensichtlichen Fällen werden Programmierer (aus Faulheit, nehme ich an, weil sie keine Zeit damit verschwenden wollen) die Commit-Protokolle nicht überprüfen und einige wichtige Informationen übersehen, während ein 10-Zeichen-Kommentar darauf hinweisen kann die richtige Fehler-ID, die selbst die Protokolle der zu diesem Fehler gehörenden Revisionen enthält, wenn Sie SCM und Tracker für die Zusammenarbeit eingerichtet haben. Wirklich das Beste von allen Welten.
Haylem

Nach meiner Erfahrung werden Commit-Nachrichten häufig ausgelassen (trotz Richtlinien, die sie einschließen, falls überhaupt vorhanden) oder sind nutzlos (nur eine Ausgabenummer und häufig die falsche). Dieselben Leute werden jedoch Kommentare im Code hinterlassen ... Ich hätte lieber diese und keine Commit-Nachricht als gar nichts (und in vielen Umgebungen war es so schwierig, die Commit-Nachrichten / den Quellverlauf abzurufen, dass es fast unmöglich war (bis einschließlich der Anforderung von Quellen von anderen Personen, da der Zugriff auf die Versionskontrolle "aus Sicherheitsgründen" beschränkt war).
Mittwoch,

3

Wir verwenden diese Vorgehensweise für Dateien, die nicht der Versionskontrolle unterliegen. Wir haben RPG-Programme, die auf einem Großrechner laufen, und es hat sich als schwierig erwiesen, viel mehr zu tun, als sie zu sichern.

Für versionierten Quellcode verwenden wir die Check-in-Hinweise. Ich denke, dort gehören sie hin, nicht dort, wo Code überfüllt ist. Es sind schließlich Metadaten.


Ich bin damit einverstanden, dass Dateien, die nicht der Versionskontrolle unterliegen, eine andere Geschichte haben.
Joshua Smith

1
"Es hat sich als schwierig erwiesen, viel mehr zu tun als sie zu sichern." Ist nicht wirklich eine Entschuldigung, die mein CTO ertragen würde.
Tim Williscroft

@Tim: Immer offen für Vorschläge - ich kann sie in die Befehlskette rücken. :) Es ist schwierig, mit dem Mainframe zu arbeiten, um Dateien aus- und wieder einzuschalten.
Michael K

Mein Vorschlag - wahrscheinlich können Sie sie entfernen (Backup); warum sollte man das nicht einfach irgendwo ablegen und jede Nacht ein kleines Skript dazu bringen, Änderungen an mercurial vorzunehmen?
Wyatt Barnett

2

Wir hatten diese Praxis vor langer Zeit in einem SW-Geschäft, in dem unser Manager darauf bestand, dass er Codedateien auf Papier lesen und deren Änderungsverlauf verfolgen wollte. Unnötig zu erwähnen, dass ich mich an keinen konkreten Anlass erinnere, als er sich tatsächlich einen Ausdruck einer Quelldatei angesehen hat: - /

Glücklicherweise wissen meine Manager seitdem besser, was Versionskontrollsysteme können (ich muss hinzufügen, dass wir SourceSafe in diesem ersten Shop verwendet haben). Daher füge ich dem Code keine Versionsmetadaten hinzu.


2

Es ist im Allgemeinen nicht erforderlich, wenn Ihr SCM und Ihre IDE die Verwendung der Funktion "show annotation" (in Eclipse sowieso als "show annotation" bezeichnet) zulassen. Sie können leicht sehen, welche Festschreibung (en) einen Codeteil geändert haben, und die Festschreibungskommentare sollten angeben, wer und warum.

Das einzige Mal, dass ich einen Kommentar wie diesen in den Code einfügen würde, ist, wenn es sich um einen besonders seltsamen Code handelt, der in Zukunft Verwirrung stiften könnte. Ich werde ihn kurz mit der Fehlernummer kommentieren, damit er zum Fehlerbericht gehen und ihn lesen kann im Detail darüber.


"Es wird nicht erwartet, dass Sie dies verstehen" ist wahrscheinlich ein schlechter Kommentar, der in den Code eingefügt werden muss. Nochmals, ich sage, verknüpfe deinen SCM und deinen Bug-Tracker miteinander.
Tim Williscroft

2

Es ist offensichtlich, dass solche Kommentare mit der Zeit fast garantiert falsch sind. Wenn Sie eine Zeile zweimal bearbeiten, fügen Sie zwei Kommentare hinzu? Wohin gehen sie? Ein besserer Prozess ist es, sich auf Ihre Werkzeuge zu verlassen.

Dies ist ein Zeichen dafür, dass sich der leitende Entwickler aus irgendeinem Grund nicht auf den neuen Prozess zum Nachverfolgen von Änderungen und zum Verbinden von Änderungen mit dem Fehlerverfolgungssystem verlassen kann. Sie müssen dieses Problem beheben, um den Konflikt zu lösen.

Sie müssen verstehen, warum er sich nicht darauf verlassen kann. Sind es alte Gewohnheiten? Eine schlechte Erfahrung mit dem SCM-System? Ein Präsentationsformat, das für ihn nicht funktioniert? Vielleicht weiß er nicht einmal, welche Tools wie "git blame" und die Timeline-Ansicht von Perforce (die im Wesentlichen dies zeigt, obwohl sie möglicherweise nicht anzeigt, welches Problem die Änderung ausgelöst hat).

Ohne seinen Grund für die Anforderung zu verstehen, werden Sie ihn nicht überzeugen können.


2

Ich arbeite an einem über 20 Jahre alten Windows-Produkt. Wir haben eine ähnliche Praxis, die es schon lange gibt. Ich kann nicht zählen, wie oft diese Übung meinen Speck gerettet hat.

Ich bin damit einverstanden, dass einige Sachen überflüssig sind. Früher verwendeten Entwickler diese Methode, um Code zu kommentieren. Wenn ich dies überprüfe, fordere ich sie auf, den Code zu löschen, und der Kommentar ist nicht erforderlich.

Aber oft sieht man sich Code an, der seit ungefähr einem Jahrzehnt von 20 Entwicklern modifiziert, aber nie überarbeitet wurde. Jeder hat längst alle Anforderungsdetails vergessen, die im Originalcode enthalten waren, und es gibt keine verlässliche Dokumentation.

Ein Kommentar mit einer Fehlernummer gibt mir die Möglichkeit, den Ursprung des Codes nachzuschlagen.

Das SCM-System leistet also viel, aber nicht alles. Behandeln Sie diese wie jeden anderen Kommentar und fügen Sie sie hinzu, wenn eine wesentliche Änderung vorgenommen wird. Der Entwickler, der sich Ihren Code in mehr als 5 Jahren ansieht, wird sich bei Ihnen bedanken.


1

Wenn Sie ein VCS haben, ist es sinnlos, jede Änderung in den Kommentaren zu erwähnen. Das Erwähnen eines bestimmten Fehlers oder eines anderen wichtigen Hinweises in Bezug auf eine bestimmte Zeile ist nützlich. Eine Änderung kann viele geänderte Zeilen enthalten, die sich alle unter derselben Festschreibungsnachricht befinden.


1

Nicht, dass ich es sagen könnte.

Ich schreibe TODOs in meinen Code, während ich fortfahre, und das Ziel ist es, sie bei der Überprüfung zu entfernen.

Durch die Nutzung unserer Website bestätigen Sie, dass Sie unsere Cookie-Richtlinie und Datenschutzrichtlinie gelesen und verstanden haben.
Licensed under cc by-sa 3.0 with attribution required.