Ist es gut, die Bugfix-Kommentare im Code zu belassen?

Mein Team verwendet Klartext als Versionskontrolle. Das Projekt, an dem ich arbeite, wurde vor 7-8 Jahren noch nicht begonnen. Während der gesamten Laufzeit des Projekts gab es mehrere Releases, in denen Fehlerbehebungen, Service Packs usw. veröffentlicht wurden. Die Probleme werden mithilfe des Fehlerverfolgungssystems nachverfolgt. Die meisten Personen, die an den Fehlerbehebungen arbeiten, folgen der Routine, den Kommentar in START / einzuschließen. END-Block mit Datum, Autor, Bug-ID usw.

Ich bin der Meinung, dass dies irrelevant ist und den Code unübersichtlich und pflegeleicht macht. Dies sind die Dinge, die Teil von Check-in-Kommentaren / -Labels usw. sein müssen, in denen wir zusätzliche Informationen zum Lebenszyklus des Arbeitsprodukts aufbewahren können.

Was ist die beste Vorgehensweise?

Einige der Überprüfer des Codes bestehen darauf, die Kommentare zu dem Fehler und die Fehlerbehebungen zu veröffentlichen, um ihr Leben zu erleichtern. Nach meinem Verständnis müssen sie die Dateien überprüfen, indem sie sie einer Ansicht zuordnen, das Änderungsprotokoll der Verzweigung abrufen und überprüfen. Es wäre hilfreich, wenn ich einige bewährte Methoden zum Einreichen des aktualisierten Codes zur Überprüfung erhalten könnte.

Das Problem beim Hinzufügen des Bugfixes als Kommentar zum Code ist, dass Sie nicht die vollständige Story erhalten. Wenn ich ein perfektes Stück Code sehe, das mit "this is a fix to the bug blah " markiert ist , würde meine erste Reaktion darin bestehen, "na und?" Zu sagen. Der Code ist da, es funktioniert. Das einzige, was ich wissen muss, um den Code zu pflegen, ist ein Kommentar, der mir sagt, was er tut.

Eine bessere Methode ist das Hinzufügen von Bugfix-Referenzen in SCM-Commit-Protokollen. Auf diese Weise sehen Sie, was der Fehler ist, wo er eingeführt wurde und wie er behoben wurde. Wenn die Zeit für eine Veröffentlichung kommt, können Sie einfach die SCM-Protokolle extrahieren und einen Aufzählungspunkt hinzufügen, der besagt, dass ein Fehler aufgetreten ist und dieser behoben wurde. Wenn in einem anderen Zweig oder einer anderen Version derselbe Fehler auftritt, können Sie den Fix leicht finden und erneut anwenden, wenn es sich tatsächlich um dasselbe handelt.

Nach alledem stimme ich auch der Antwort von Charles zu. Wenn der Grund für einen Code nicht offensichtlich ist, teilen Sie dem Betreuer auf jeden Fall mit, dass der Code aus einem bestimmten Grund vorhanden ist und mit Sorgfalt behandelt werden sollte.

Meistens schlechte Praxis. Ich werde nicht sagen, dass es niemals getan werden sollte. Gelegentlich stoßen Sie auf einen Fehler in einer externen API, den Sie umgehen müssen. Die Problemumgehung kann völlig hirntot aussehen, wenn Sie den zugrunde liegenden Fehler nicht kennen. In diesem Fall ist es möglicherweise eine gute Idee, den Fehler im Code zu dokumentieren, damit Mitarbeiter oder Ihr späteres Selbst nicht versuchen, den offensichtlich gehirntoten Code zu "reparieren".

Schlechte Übung. Kommentare werden veraltet sein und den Code überladen. Die Informationen sind bei Bedarf weiterhin in der Versionshistorie Ihres SCC-Systems verfügbar.

Klingt nach einer schlechten Übung. Was passiert, wenn Ihre Organisation auf ein anderes Bug-Tracking-System migriert? Binden Sie Ihr Produkt nicht zu fest an die Werkzeuge, die Sie gerade verwenden. Anstatt auf bestimmte Fehler-IDs zu verweisen und die Gründe für die Unklarheit des Codes zu nennen, sollten Sie Ihre Entwurfsentscheidung mit Kommentaren im Code begründen.

Meine erste Reaktion wäre, dass Sie sich nicht wiederholen. Raus aus dem Code und rein in die SCM-Protokolle. Wir haben hier eine ähnliche Diskussion über Revisionskommentare für Funktionen, Autorennamen und Erstellungsdaten für Dateien und Funktionen geführt. In der Vergangenheit (vor der Verwendung von SCM) wurden alle diese Informationen in den Dateien gespeichert, um die Entwicklung einer Datei nachvollziehen zu können.

Etwa die Hälfte der Entwickler möchte, dass diese Informationen alle Informationen an einem Ort haben (dies veranlasst sie, nach Änderungen im SCM zu suchen). Die andere Hälfte der Entwickler beginnt nicht mit der Suche nach Hinweisen darauf, was sich im Code geändert hat, sondern über das SCM, sodass sie die Informationen im Code nicht benötigen. Wir müssen noch eine Entscheidung treffen, was mit diesen Kommentaren geschehen soll. Es hängt stark von der Art und Weise ab, wie Menschen arbeiten, und manche Menschen sind sehr hartnäckig dabei, ihre bekannten Methoden zu verlassen. Das Gleiche gilt für das Auskommentieren von Codeblöcken und für die Ewigkeit im Code belassen.

Nur um hinzuzufügen, was Dyaster et al. Ich habe gesagt, obwohl JIRA wirklich gute Möglichkeiten hat, Änderungen im Zusammenhang mit Bugfixes anzuzeigen, ist der absolut beste Ort, um einen Bugfix zu dokumentieren, ein Testfall. Wenn der Code nicht klar ist, ohne dass ein Kommentar dahingehend angezeigt wird, welcher Fehler behoben wurde, ist dies "Code-Geruch". Wenn Sie jedoch keine Zeit haben, den Geruch zu bereinigen, sollte sich der Kommentar auf den Testfall beziehen, bei dem es viel offensichtlicher sein sollte, warum der Code das tut, was er tut. Wenn Sie keine Zeit haben, einen Testfall zu schreiben, der die Fehlerbehebung erklärt, wurde der Fehler noch nicht wirklich behoben, sondern nur verschoben.

Ich würde dem Hinzufügen von Bugfix-IDs in Commit-Nachrichten und nicht im Code selbst zustimmen. Bug Tracker, die Commit-Nachrichten automatisch nach Bug-IDs durchsuchen, sind sehr nützlich.

Darüber hinaus können Sie den Befehl blame / annotate / praise Ihres Versionskontrollsystems verwenden, um diese Kommentare zu ersetzen. Wenn Sie dann etwas ausführen wie:

vcs blame file.ext

Sie sehen nützliche Informationen, in der Regel auch, wer die einzelnen Zeilen geändert hat, wann sie geändert wurden, und die Festschreibungs-ID. Aus der Festschreibungs-ID können Sie die vollständige Nachricht abrufen, die die Fehler-ID enthalten sollte.

In guten VCS-Systemen können Sie Leerzeichen ignorieren, wenn Sie berechnen, wer eine Zeile geändert hat.

Ich weiß nicht, was Clear Case für diese Funktion hat.