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

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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