Configuration Management - Geschichte in Code Kommentare

Question

Lassen Sie mich ein wenig Hintergrundinformationen stellen, bevor meine Frage:

Ich kam vor kurzem eine neue Software-Entwicklungsgruppe, die Rational-Tools für das Konfigurationsmanagement verwendet, einschließlich einer Quellensteuerung und Change-Management-System. Zusätzlich zu diesen Tool, hat das Team eine gängige Praxis von der Feststellung, keine Änderungen am Code als Kommentar im Code, wie zum Beispiel:

///<history>
   [mt] 3/15/2009  Made abc changes to fix xyz
///</history>

Ihre offizielle Aufgabe für die Kommentierung Standard ist, dass „die Kommentare Rückverfolgbarkeit von Anforderungen zu Code-Änderung zur Verfügung stellen“.

Ich bereite ein Argument zu stellen, dass diese Praxis unnötig und überflüssig ist; dass das Team dieses Standards befreien sofort bekommen sollte.

Nämlich - das Change-Management-System ist der Ort, um die Rückverfolgbarkeit von Anforderung zu bauen Modifikation zu codieren, und Quellcodeverwaltung kann detaillierte Historie der Änderungen bereitzustellen, indem eine Diff zwischen den Versionen durchführen. Wenn Quellcode wird eingecheckt, wird das entsprechende Change Management Ticket zur Kenntnis genommen. Wenn ein CM-Ticket gelöst ist, stellen wir Dateien, die Quellcode geändert wurden. Ich glaube, das einen ausreichenden Querverweis für die gewünschte Rückverfolgbarkeit zur Verfügung stellt.

Ich möchte wissen, ob jemand mit meinem Argument nicht einverstanden ist. Fehle ich einige Vorteile von kommentierten Quellcode Geschichte, die Verwaltung und Versionsverwaltungssysteme ändern nicht bieten kann?

Answer 1

Für mich, ich habe immer gefunden, solche Kommentare mehr Ärger als sie wert sind: sie verursachen Konflikte zusammenführen können, können als ‚False Positives‘ angezeigt, wenn Sie versuchen, die Diffs zwischen zwei Versionen zu isolieren und kann Referenzcodeänderungen, die seitdem durch spätere Änderungen verworfen haben.

Es ist oft (nicht immer, aber oft) möglich Versionskontrollsysteme zu ändern, ohne Metadaten zu verlieren. Wenn Sie waren Ihr Code auf ein System zu bewegen, dass nicht unterstützen dies, wäre es nicht schwer sein, ein Skript zu schreiben die Änderungshistorie in Kommentare vor dem cutover zu konvertieren.

Answer 2

Ein Kommentar können Sie alle Änderungen und ihre Gründe in der Code richtig finden, wo sie ohne in diffs und Versionskontrollsystem Feinheiten zu graben relevant sind. Darüber hinaus sollten Sie sich entscheiden, von Versionskontrollsystem zu ändern, bleiben die Kommentare.

Ich arbeitete an einem großes Projekt mit ähnlicher Praxis, die zweimal von Quellensteuersystem verändert hatte. Es gab keinen Tag, an dem ich nicht froh war, diese Kommentare zu haben.

Ist es überflüssig? Ja. Ist es nicht notwendig? Nr.

Answer 3

Ich habe immer gedacht, dass Code sollte sein, natürlich unter Versionskontrolle, und das die aktuelle Quellcode (die, die Sie öffnen und lesen können heute) sollte gültig sein nur im Präsens .

Es spielt keine Rolle, ob ein Bericht bis zu 3 Achsen in der Vergangenheit und im letzten Monat Sie es bis zu 6 Achsen zur Unterstützung von bis aktualisiert haben könnte. Es spielt keine Rolle, ob Sie eine Funktion oder festen einige Fehler erweitert, solange die aktuelle Version leicht verstanden werden kann. Wenn Sie einen Fehler beheben, lassen Sie einfach den festen Code.

Es gibt eine Ausnahme. Wenn (und nur dann) der feste Code sieht weniger intuitiv zu Ihnen als die vorherigen, fehlerhaftem ein; wenn Sie das Gefühl, dass jemand morgen kommen könnte und nur durch Lesen des Codes, versucht sein, ihn zu ändern zurück zu dem, was „scheint mehr richtig“ , dann ist es gut, um einen Kommentar hinzuzufügen: "Dies geschieht dies Art und Weise ... zu vermeiden, bla bla bla. " auch hinter wenn das Problem ist ein berüchtigter Kriegsgeschichte innerhalb der Kultur des Teams, oder wenn aus irgendeinem Grunde die Fehlerbericht-Datenbank sehr interessante Informationen über diesen Teil des Codes enthält , würde ich es nicht falsch finden in zur Erläuterung Kommentar "(Fehler-ID 10005 sehen)".

Answer 4

Die eine, die mir in den Sinn springt ist Lock-In-Effekt. Wenn Sie jemals von Rational weggezogen, würden Sie müssen sicherstellen, dass die vollständige Änderungshistorie wurde während der Migration beibehalten -. Nicht nur die Version der Artefakte

Answer 5

Wenn Sie im Code sind müssen Sie wissen, warum es so strukturiert ist, also im Code zu kommentieren. Werkzeuge, die außerhalb des Codes sitzen, gut sie auch sein mag, erfordern viel zu viel von einer Kontextverschiebung im Gehirn nützlich zu sein. Sowie, dass der Code Absicht von Dokumentation Reverse Engineering versuchen und ein diff ist verdammt hart, ich würde viel lieber eine Kommentar-Zeile liest jeden Tag möglich.

Answer 6

Es gab eine Phase im Code arbeite ich an, wieder in dem 1994-1996 Zeitrahmen, wo es eine Tendenz, Änderungshistorie Kommentare am Anfang der Datei einfügen. Diese Kommentare sind jetzt sinnlos und nutzlos, und einer der vielen Standard-Bereinigungen führe ich bei der Bearbeitung von Dateien, die solche Kommentare ist es, sie zu entfernen.

Im Gegensatz dazu gibt es auch einige Kommentare mit einer Fehlernummer an der Stelle, wo die Änderung vorgenommen wird, in der Regel zu erklären, warum der lächerliche Code ist wie es ist. Diese können sehr hilfreich sein. Die Fehlernummer gibt Ihnen woanders nach Informationen zu suchen, und die Finger der Täter. (Oder Opfer - es variiert)

Auf der anderen Seite, Artikel wie dieser - echt; letzte Woche aufgeräumt -. machen mir meine Zähne zusammenbeißen

    if (ctab->tarray && ctab->tarray[i])
#ifndef NT
      prt_theargs(*(ctab->tarray[i]));
#else
      /* Correct the parameter type mismatch in the line above */
      prt_theargs(ctab->tarray[i]);
#endif /* NT */

Das NT-Team bekam den Anruf richtig; warum sie dachten, es war eine plattformspezifische fix ist mir schleierhaft. Natürlich, wenn der Code Prototypen statt nur parameterlos Erklärungen vor jetzt benutzt hatte, dann würde das Unix-Team auch den Code zu beheben hatte. Der Kommentar war eine Hilfe - und versichert mir, dass der Bug war echt -. Aber zum Verzweifeln