Ist es sinnvoll, ein Änderungsprotokoll in jede Codedatei aufzunehmen, wenn Sie die Versionskontrolle verwenden?


75

Ich hatte den Eindruck, dass ein Versionskontrollsystem die Notwendigkeit beseitigt, überall im Code Änderungsprotokolle anbringen zu müssen. Ich habe oft die fortgesetzte Verwendung von Änderungsprotokollen gesehen, einschließlich großer langer Blöcke zu Beginn gespeicherter Prozeduren, wobei ein großer Abschnitt für Änderungen an der Datei gesperrt und der Code mit Dingen wie folgendem übersät wurde:

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

und:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

Der Grund dafür ist, wie mir erklärt wurde, dass das Durchsuchen unserer VCS-Protokolle zu lange dauert, um herauszufinden, wer was und warum geändert hat, während es sich in der Codedatei befindet, entweder oben oder in der Nähe der relevanten ändern, macht es einfach zu sehen, wer was wann geändert hat. Ich verstehe zwar den Punkt, aber es scheint überflüssig und schmeckt nur nach "Ähm, wir verstehen nicht wirklich, wie wir unser VCS richtig einsetzen, also werden wir uns überhaupt nicht darum kümmern."

Was denkst du? Verwenden Sie sowohl Kommentare als auch das Protokoll? Nur das Protokoll? Finden Sie es einfacher zu codieren, wenn Sie über einem Codeblock sehen, dass John Smith die Methode geändert hat, um vor einer Woche nach XYZ zu suchen, anstatt Protokolle durchsuchen und Codedateien in einem Diff-Tool vergleichen zu müssen?

BEARBEITEN: Mit SVN, aber im Grunde nur als Repository. Keine Zweige, keine Zusammenführungen, nichts außer log + storage.


4
Welches Versionskontrollsystem verwenden Sie?
ChrisF

11
Einige Geschäfte verwendeten Änderungsprotokolle, bevor es Versionsverwaltungssysteme gab. Trägheit und Vertrautheit führen die Änderungsprotokolle.
Gilbert Le Blanc

2
+1 - Mein Team tut dies auch und ich habe versucht, einige von ihnen davon zu überzeugen, dass es die Rolle des VCS ist. Das Problem beginnt, wenn diese Kommentare nicht mit dem tatsächlichen Code auf dem neuesten Stand gehalten werden ... Und das Schlimmste ist, dass das Management beschlossen hat, jeder Methode auch Änderungsprotokolle hinzuzufügen.
Slaphappy

2
+1 - Ich habe fast zwei Jahre lang mit unserem Senior-Entwickler darüber gestritten. Seine einzige Begründung für das Hinzufügen dieser nutzlosen Kommentare ist, dass das Zusammenführen von Änderungen an Methoden mit 3000 Zeilen ein wenig einfacher ist. Die Vorstellung, dass eine 3000-Zeilen-Methode obszön ist, stößt auf Verachtung.
Joshua Smith

1
Wenn es "zu lange dauert, [Ihre] VCS-Protokolle zu durchsuchen", machen Sie etwas falsch.
Keith Thompson

Antworten:


46

Ich neige dazu, Kommentare im Code zu löschen. Und mit streichen meine ich, mit Vorurteilen . Wenn ein Kommentar nicht erklärt, warum eine bestimmte Funktion etwas bewirkt, geht sie verloren. Tschüss. Geh nicht vorbei.

Es sollte Sie also nicht überraschen, dass ich aus dem gleichen Grund auch diese Änderungsprotokolle löschen würde.

Das Problem mit auskommentiertem Code und Kommentaren, die sich wie Bücher lesen, ist, dass Sie nicht wirklich wissen, wie relevant sie sind, und dass Sie falsch verstehen, was der Code tatsächlich tut.

Es hört sich so an, als ob Ihr Team keine guten Werkzeuge für Ihr Versionskontrollsystem hat. Da Sie gesagt haben, dass Sie Subversion verwenden, möchte ich Sie darauf hinweisen, dass es viele Tools gibt, mit denen Sie Ihr Subversion-Repository verwalten können. Von der Möglichkeit, Ihre Quelle durch das Web zu navigieren und Ihre Änderungssätze mit bestimmten Fehlern zu verknüpfen, können Sie eine Menge tun, um die Notwendigkeit dieser "Änderungsprotokolle" zu verringern.

Ich habe viele Leute dazu gebracht, Kommentare abzugeben und zu sagen, dass ich beim Löschen von Kommentaren möglicherweise im Irrtum bin. Die überwiegende Mehrheit des Codes, den ich gesehen habe, der kommentiert wurde, war fehlerhafter Code, und die Kommentare haben das Problem nur verschleiert. In der Tat, wenn ich jemals Code kommentiere, können Sie sicher sein, dass ich den Wartungsprogrammierer um Verzeihung bitte, weil ich relativ sicher bin, dass sie mich töten wollen.

Aber damit Sie nicht denken, dass ich sage, dass Kommentare im Scherz gelöscht werden sollten, veranschaulicht diese tägliche WTF-Einreichung (aus einer Codebasis, an der ich gearbeitet habe) meinen Standpunkt perfekt:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

Oh ... Die Geschichten, die ich Ihnen über diese Codebasis erzählen könnte, und ich würde, außer dass sie noch von einer der größten Regierungsorganisationen in Gebrauch ist.


4
Immer wenn ich mit einem bestimmten Teil komplexer Logik zu kämpfen habe, helfen mir Kommentare manchmal dabei, einen Zusammenhang zu erkennen, warum die Logik so verwickelt ist wie sie ist. Aber im Großen und Ganzen stimme ich Ihnen zu.
maple_shaft

5
Jeder Entwickler hat mindestens ein paar schlechte Eigenschaften, ich weiß, ich sollte nicht, aber ich kann einfach nicht aufhören :) Jedes Mal, wenn ich einen TODOKommentar verfasse, stirbt ein Welpe.
maple_shaft

32
Das Löschen von Kommentaren anderer Leute mit Vorurteilen erzwingt in gewisser Weise Ihren eigenen Programmierstil und Glauben an andere. Junioren und pazifistische Programmierer bellen nicht zurück, aber hin und wieder stößt man auf einen Alpha-Mann, und dann beginnt ein Kampf, der eigentlich nicht hätte sein dürfen. Sie haben in einem intelligenten Blog einer intelligenten Person gelesen, dass weniger mehr ist, wenn es um Kommentare geht. Andere haben vielleicht nicht dasselbe Buch gelesen. Auch wenn Sie denken, Sie haben Recht, weil einige Leute mit 5k + rep auf SO übereinstimmen, ist Diktatur nicht der richtige Weg, um kollaborativ zu arbeiten. Ich habe vorher unter einem Alpha-Mann gearbeitet und gekündigt.
Job

8
@ Neil Butterworth: Re: ructions: Code soll formbar sein. Refactor es, ändern Sie es, verbessern Sie es. Es ist dafür gedacht. Es soll nicht nur einmal geschrieben werden. Unser Verständnis des Geschäfts ändert sich, und wenn dies geschieht, müssen wir den Code ändern. Ich habe viele Probleme mit Kommentaren, aber das Wichtigste für unsere Diskussion ist, dass Kommentare selten mit dem Code synchron bleiben und im Allgemeinen nicht erklären, warum etwas passiert. Wenn das passiert, ist es einfach, es zu löschen. Wenn jemand zu mir kommt und fragt, warum ich den folgenden Kommentar gelöscht habe file.Open() // Open the file. Ich würde lachen.
George Stocker

5
Vor ein paar Tagen habe ich ein Stück Code geschrieben, eine sehr komplexe mathematische Berechnung voller Trigonometrie, Transformationen, was auch immer ... Ich habe ungefähr anderthalb Stunden gebraucht, um weniger als 10 Zeilen Code zu schreiben. So gut wie niemand um mich herum versteht, wie es funktioniert. Ich werde es in ein paar Wochen auch nicht verstehen. Auf der anderen Seite, warum es dort ist trivial. Über diesen wenigen Zeilen befindet sich ein ganzes Textkapitel, in dem erklärt wird, was und nicht warum. Wenn du gekommen wärst und diesen Kommentar gelöscht hättest, hätte ich dir ins Gesicht geschlagen und die Schraube abgefeuert.
Davor Ždralo

76

Die im Code eingebetteten "Änderungsprotokolle" sind besonders unpassend. Sie zeigen nur einen weiteren Unterschied, wenn Sie Revisionen unterscheiden, und einen, den Sie nicht wirklich interessieren. Vertrauen Sie Ihrem VCS - die meisten haben eine "Schuld" -Funktion, die Ihnen sehr schnell zeigt, wer was geändert hat.

Das wirklich Schreckliche war natürlich die Funktion von "alten" VCS, bei der das eigentliche VCS-Protokoll in die Quelldateien eingebettet werden konnte. Verschmelzung fast unmöglich gemacht.


14
Sie stellen nicht nur einen weiteren Unterschied dar, sondern können sich auch im Laufe der Zeit als falsch herausstellen, während jedes gute VCS Ihnen immer sagen kann, wer wirklich eine bestimmte Zeile geschrieben hat, sowie die Geschichte um diese Zeile herum. Das einzige, was schlimmer ist als nutzlose Kommentare, sind schädliche Kommentare. Diese Kommentare beginnen als nutzlos und werden schließlich schädlich, wenn sie nicht vollständig ignoriert werden.
Ben Hocking

10

Ich habe eine einzelne ChangeLog-Datei für jedes Projekt, die automatisch mit bestimmten Commit-Nachrichten gefüllt wird.

Wir haben keine ChangeLog-Kommentare eingebettet. Wenn wir das tun, würde ich sie entfernen und mit der Person, die sie hinzufügt, "sprechen". Ich denke, sie deuten darauf hin, dass Sie die von Ihnen verwendeten Tools, insbesondere die vcs, nicht verstehen.

Wir haben ein Format für Commit-Nachrichten, das es einfacher macht, die Protokolle zu durchsuchen. Wir verbieten auch nutzlose oder mehrdeutige Commit-Nachrichten.


8

Ich persönlich verabscheue Änderungsprotokolle in der Quellcode-Datei. Für mich fühlt es sich einfach so an, als würde es ein Prinzip der Softwareentwicklung verletzen, indem jede Änderung, die ich vornehme, an mehreren Stellen vorgenommen werden muss. Häufig sind die Änderungsprotokollinformationen völlig nutzlos und unwichtig. Meiner bescheidenen Meinung nach sollten Änderungen an der Software dokumentiert werden, wenn Sie den Code einchecken.

Aber was weiß ich schon ...

Ich bin der Meinung, dass das Änderungsprotokoll auf Änderungen beschränkt werden sollte, die sich auf die Pulic-API / -Schnittstelle der Klasse auswirken, wenn bei der Implementierung der Praxis, ein Änderungsprotokoll im Quellcode zu führen, ein Widerspruch besteht. Wenn Sie in der Klasse Änderungen vornehmen, die keinen Code beschädigen, der sie verwendet, ist das Aufzeichnen dieser Änderungen in einem Änderungsprotokoll meiner Meinung nach nur ein Durcheinander. Ich kann jedoch feststellen, wie nützlich es manchmal sein kann, den Anfang der Quellcodedatei auf Änderungen zu überprüfen, die für andere Personen möglicherweise einen Fehler verursacht haben. Nur eine Zusammenfassung, wie sich die Änderung auf die API auswirken könnte und warum die Änderung vorgenommen wurde.

Auf der anderen Seite arbeitet mein Shop hauptsächlich mit C #. Wir verwenden immer Inline-XML-Kommentare, um unsere API zu dokumentieren. Das Lesen der Dokumentation zu öffentlichen API-Änderungen ist also mehr oder weniger so einfach wie die Verwendung von Intellisense.

Ich denke, dass das Beharren auf einem Änderungsprotokoll in der Quelldatei nur unnötige Reibung auf dem Computer verursacht und einen der Zwecke der Implementierung eines Versionskontrollsystems zunichte macht.


6

Das letzte Unternehmen, bei dem ich gearbeitet habe, verfügte über Software mit einer 17-jährigen Geschichte, Entwicklung und jährlichen Updates. Nicht bei allen Migrationen von einem Versionskontrollsystem zum nächsten bleiben Kommentare oder Check-in-Hinweise erhalten. In diesen Jahren haben auch nicht alle Entwickler die Übereinstimmung mit den Kommentaren / Anmerkungen zum Einchecken aufrechterhalten.

Mit Kommentaren im Quellcode wurde die archäologische Geschichte der Änderungen als Notizen gespeichert und nicht als Code auskommentiert. Und ja, sie liefern immer noch VB6-Code aus.


5

Die Versionskontrolle kann diese Änderungsprotokollkommentare im Code ersetzen, wenn die Entwickler Ihres Teams sie ordnungsgemäß verwenden.

Wenn Ihr Team beim Einchecken keine Kommentare hinzufügt oder nicht hilfreiche Kommentare hinterlässt, ist es ziemlich schwierig, die Informationen zu finden, nach denen Sie in Zukunft suchen.

In meiner derzeitigen Firma müssen wir bei jedem Check-in einen Kommentar abgeben. Darüber hinaus wird von uns erwartet, dass wir jedem Check-in ein Ticket in Jira beilegen. Wenn Sie in Zukunft in Jira suchen, sehen Sie jede Datei, die eingecheckt wurde, und wann für dieses Problem, zusammen mit dem Kommentar, der hinterlassen wurde. Es ist ziemlich praktisch.

Grundsätzlich ist die Versionskontrolle nur ein Tool. Ihr Team verwendet dieses Tool, um die gewünschten Vorteile zu erzielen. Jeder im Team muss damit einverstanden sein, wie er es am besten einsetzen wird, um Fehlerbehebungs-Tracking sowie saubere Code-Revisionen bereitzustellen.


5

Dies ist ein Überbleibsel aus den Tagen, als VCS-Protokolle verwirrend und VCS-Systeme schwierig zu handhaben waren (ich erinnere mich an diese Tage, irgendwo im Backend der 80er Jahre).

Ihr Verdacht ist völlig richtig, diese Kommentare sind eher ein Hindernis als eine Hilfe, und mit jedem modernen VCS können Sie genau das finden, wonach Sie suchen. Natürlich müssen Sie (und Ihre Kollegen) ca. 30-60 Minuten lernen, wie man all diese Funktionen steuert (was, wie ich vermute, eigentlich der Grund ist, warum diese Kommentare immer noch da sind).

Ich behalte es (fast) bei George. Kommentare im Code sind nur dann wirklich gerechtfertigt, wenn sie etwas erklären, das im Code selbst nicht sofort sichtbar ist. Und das kommt in gutem Code nur selten vor. Wenn Sie die Notwendigkeit haben, viele Kommentare in Ihrem Code zu haben, ist das ein Eigengeruch und es ruft "Refactor me!".


4

Wir nehmen sie dennoch in die Quelle für gespeicherte Prozeduren auf, da wir auf diese Weise genau feststellen können, welche Version auf einem Client vorhanden ist. Der Rest der Anwendung wird kompiliert verteilt, daher verfügen wir über Modulversionsnummern, die auf den Quellcode verweisen. Die SPs werden jedoch als Quellcode für die lokale Kompilierung in der Datenbank an die Clients verteilt.

Unser älterer PowerBuilder-Code verwendet sie immer noch, aber ich denke, das ist nur ein Trostfaktor für bestimmte Leute. Das wird auch für die Verteilung kompiliert, also sollten sie (IMO) die verdammte VCS-Geschichte verwenden.


1
+1 Ich wollte diese Antwort schreiben, aber du hast mir die Mühe erspart. Nicht nur gespeicherte Prozeduren werden als Quelle verteilt, sondern auch viele Skriptsprachen. Ich verwende häufig OpenACS und TCL. Wenn ein Client eine gespaltene Version einer bestimmten Datei hat, können Sie nur durch Lesen des Änderungsprotokolls sicherstellen, dass Sie wissen, welche Version er hat. Besonders praktisch, wenn Sie auf der Website eines Kunden angemeldet sind und mit der Versionskontrollsoftware keine Unterschiede feststellen können.
TrojanName

3

Wenn Sie SVN verwenden, ist dies Zeitverschwendung und völlig nutzlos.

SVN hat die Schuldfunktion. Dadurch erfahren Sie genau, wer und wann jede Zeile in einer bestimmten Datei erstellt hat.


1

Änderungsprotokollkommentare sind im Code besonders hilfreich, wenn sie einem nachfolgenden Entwickler helfen, bessere Fragen zu neuen Anforderungen zu stellen. Wenn ein Entwickler einen Kommentar sieht, zum Beispiel, dass Fred das Foo-Feld vor 6 Monaten ausgefüllt hat, um eine bestimmte Anforderung zu erfüllen, weiß er, dass er eine Frage stellen muss, bevor er die letzte Anforderung implementiert, um Foo optional zu machen. Bei komplexen Systemen haben unterschiedliche Stakeholder wahrscheinlich unterschiedliche Prioritäten und Wünsche. Änderungsprotokollkommentare können sehr hilfreich sein, um zu dokumentieren, welche dieser Kompromisse getroffen wurden, um Probleme in Zukunft zu vermeiden.

Wenn nun jeder Entwickler den vollständigen Verlauf jeder Codezeile überprüft, bevor er Änderungen vornimmt, wäre es überflüssig, diese Kommentare im Code zu haben. Dies ist jedoch sowohl vom Workflow-Standpunkt aus sehr unrealistisch - die meisten Entwickler würden lediglich die Validierung ändern, ohne nachzuforschen, wer sie hinzugefügt hat und warum - und vom technologischen Standpunkt aus würde ein Versionskontrollsystem Schwierigkeiten haben, diese zu verfolgen "Codezeile, wenn sie von einer Zeile in eine andere verschoben oder in eine andere Klasse umgestaltet wurde. Kommentare im Code sind viel wahrscheinlicher zu sehen und führen, was noch wichtiger ist, dazu, dass ein nachfolgender Entwickler feststellt, dass eine scheinbar einfache Änderung möglicherweise nicht so einfach ist.

Das heißt, Änderungsprotokollkommentare im Code sollten relativ selten sein. Ich befürworte nicht, dass Änderungsprotokollkommentare jedes Mal hinzugefügt werden, wenn ein Teil des Codes überarbeitet wird oder wenn ein echter Fehler behoben wird. Aber wenn die ursprüngliche Anforderung "Foo ist optional" war und jemand vorbeikam und die Anforderung in "Foo ist erforderlich, um die nachgelagerte Prozessleiste zu unterstützen" änderte, würde ich nachdrücklich erwägen, einen Kommentar für diese Anforderung hinzuzufügen. Da die Wahrscheinlichkeit groß ist, dass einige zukünftige Benutzer / Analysten den Downstream-Bar-Prozess und den Grund für die Anforderung von Foo nicht kennen, werden sie aufgefordert, Foo erneut als optional zu definieren, um Kopfschmerzen im Bar-Prozess zu verursachen.

Und dies bevor man bedenkt, dass sich Unternehmen möglicherweise dazu entschließen, ihr Versionskontrollsystem mit einer gewissen Häufigkeit zu ändern, zumal sie von kleinen Unternehmen mit einer Handvoll Entwicklern zu viel größeren Unternehmen heranwachsen. Diese Migrationen führen häufig zum Verlust von Änderungsprotokollkommentaren. Nur die Kommentare im Code bleiben erhalten.


Gibt es VCS-Konvertierungen, bei denen Commit-Nachrichten nicht beibehalten werden?
David Thornley

1
@ David - Ich habe viel gesehen, was nicht geschah. Ich weiß nicht, ob es technische Hindernisse gab oder ob sich jemand entschied, dass es einfacher ist, am ersten Tag einfach "neu anzufangen" und den gesamten Code für das neue VCS einzuchecken.
Justin Cave

Hinzufügen eines Kommentars, der erklärt, warum sich ein Prozess geändert hat, kann nützlich sein, und manchmal Hinzufügen eines Kommentars, der erklärt, wann sich der Prozess geändert hat , aber ich sehe keinen Sinn darin, diesen Kommentar in Form eines Änderungsprotokolls abzulegen. Zum einen wird die Nützlichkeit des Kommentars etwas verschleiert ("Oh, es ist nur ein Änderungsprotokollkommentar"), und zum anderen werden weitere unnötige Änderungsprotokollkommentare gefördert (Verstärkung 1).
Ben Hocking

Mit Visual Source Safe beenden? Alle nützlichen modernen Versionsverwaltungssysteme verarbeiten Änderungsprotokolle ordnungsgemäß. Wir wissen das per Definition, weil sie sonst nicht als nützlich angesehen würden. Verbringen Sie 30 Minuten damit, die Quellcodeverwaltung zu erlernen. Dadurch sind Sie viel effektiver, als wenn Sie nur beten, dass jemand, der Ihre Werkzeuge kennt, Ihnen einige Krümel erspart. Ganz zu schweigen davon, dass Codeverlauf oft irrelevant ist. Sie testen und schreiben jetzt nur noch.
Ebyrob

Was die "Quellcodeverwaltung" betrifft, so können fast alle modernen Systeme die Historie in die andere verschieben, einzelne Änderungsdateien auf Projektebene ausgeben oder mit geringem Aufwand ihre Änderungsprotokolle in die Quelldatei einbetten (wenn dies bei einem Umzug angebracht ist) nicht bevor). Die Technologie ist also da. Leute, die sich dafür entscheiden, die Quellcodeverwaltung nicht richtig zu verwenden, sind das Problem.
Ebyrob

1

Ich bin überrascht zu sehen, dass dies von niemandem erwähnt wurde, aber ist dies nicht der ursprüngliche Grund dafür, die Lizenzanforderungen zu erfüllen? Das heißt, einige Lizenzen besagen, dass jede Änderung, die Sie an der Datei vornehmen, in der Datei selbst vermerkt werden muss.


1
welche lizenzen sagen das
Trasplazio Garzuglio

2
Ich arbeitete an einem Ort, an dem die Sarbanes-Oxley-Konformität, an die sie glaubten, Änderungsblöcke in Quelldateien erforderte. Sie verwendeten im Laufe der Jahre auch PVCS (auch bekannt als "Dimensions"), so dass sie wirklich keinerlei Versionskontrolle hatten, aber was wusste ich?
Bruce Ediger

@Marco: Ich erinnere mich nicht oder ich hätte damit verlinkt.
Sverre Rabbelier

1
Abschnitt 2a der GPLv2 schreibt dies vor. Die meisten Projekte ignorieren dies, einige haben eine einzige "ChangeLog" -Datei (oft aus ihrem VCS generiert).
dsas

0

Der Grund dafür, dass wir weiterhin ein Änderungsprotokoll in unserem Kommentarbereich führen, ist die Benutzerfreundlichkeit. Oft ist es beim Debuggen eines Problems einfacher, zum Anfang der Datei zu scrollen und das Änderungsprotokoll zu lesen, als die Quellcodeverwaltungsdatei zu öffnen, die darin enthaltene Datei zu suchen und die vorgenommenen Änderungen zu suchen


1
Persönlich empfinde ich es als etwas mühsam, wenn eine Datei mit 200 Zeilen 1.000 Zeilen lang wird, weil jeder Quelldatei ein Änderungsprotokoll hinzugefügt wird. Dieses zusätzliche Rauschen verdeckt tatsächlich, was in Kürze wichtig ist.
Ebyrob
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.