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?

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.

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.

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.

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

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.

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.

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.