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


15

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.


3
Die eigentliche Frage ist, warum sie das so machen. Dies ist möglicherweise eine sehr alte Prozedur vor der Quellcodeverwaltung.

@anderson - Ich habe das Gefühl, dass sie nicht das richtige Verständnis für die Verwendung von Clearcase haben, als es eingeführt wurde.
Diese

darüber nachgedacht, es herauszufinden?


Ich werde nicht sagen, dass es eine schlechte Praxis ist. Auf jeden Fall ist eine der Softwarequalitätsmessungen der Prozentsatz der Kommentare im Quellcode.
Rudy

Antworten:


27

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.


Hervorragende Antwort. Ich habe meiner Frage noch ein paar Punkte hinzugefügt. Bitte überprüfe und aktualisiere deine Antwort. Danke. BTW, können Sie mir mit Clearcase-Befehlen helfen, um Commit-Protokolle von einem bestimmten Zweig zu erhalten?
Sarat

@Sarath Ich fürchte, ich habe ClearCase noch nie benutzt. Fühlen Sie sich frei, Superuser zu verwenden, um weg zu fragen. Ich bin mir sicher, dass es eine Menge Leute gibt, die bereit sind zu helfen.
Dysaster

4
Gute Bug-Tracker wie JIRA können in den Commit-Protokollen Ihres SCM nach Informationen über Fehler suchen. Stellen Sie sich vor, Sie schreiben etwas für einen Fehler fest, und der Fehlerverfolger fügt dem Fehlerbericht automatisch eine Notiz hinzu, in der X für den Fehler angegeben ist.

@Andersen - Danke, wir verwenden JIRA. Aber ich muss sicherstellen, dass es richtig funktioniert oder nicht.
Sarat

@ Thorbjørn Ah, du hast es leicht. Ich musste es früher mit CVS / Bugzilla (und später mit SVN / Bugzilla) manuell machen. Fügen Sie meinem Commit einen Bugfix-Verweis hinzu, und fügen Sie den Commit-Verweis zu Bugzilla hinzu. Fehleranfälliger Prozess, und Entwickler tendierten dazu, den einen oder anderen zu vergessen. Die Informationen haben sich jedoch mehrfach als sehr nützlich erwiesen.
Dysaster

23

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


3
Einverstanden. Fügen Sie diese Art von Kommentaren hinzu, wenn sie einen signifikanten Wert hinzufügen. Tun Sie sie jedoch nicht nur, um einen Griff zu drehen.
quick_now

Nizza, dies unterstützt die Idee von Kommentaren, die sagen "Warum", dass Code vorhanden ist. Siehe programmers.stackexchange.com/questions/1/…
Gabriel

Ich habe das ein paar Mal gemacht: Code, der sich auf den ersten Blick der Logik vollständig entzieht ("Wofür ist das f * dieser Code hier?"), Der aber tatsächlich aus einem sehr guten Grund vorhanden ist es. Wenn Sie dann einen warnenden Kommentar hinzufügen, in dem das Warum dieses Codes erläutert wird , kann dies das Leben aller erleichtern. Wenn sich dann jemand einen besseren Weg ausdenken kann, um das ursprüngliche Problem zu lösen, dann weiß er, warum der Braindead-Code eingerichtet wurde und was damit erreicht werden soll. Daher ist es viel einfacher, eine Alternative zu implementieren Lösung.
ein Lebenslauf vom

9

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


3

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.


Dies ist eine falsche Zweiteilung. Warum können Sie bei Bedarf keine Designkommentare ("Deshalb haben wir xy z gemacht") und Fehler-IDs in Commit-Nachrichten erwähnen?
Matthew Flaschen

Wo steht, dass du nicht kannst? Ich bezog mich auf Fehler-IDs im Code, nicht auf VCS-Commit-Nachrichten.
Fejd

Entschuldigung, ich habe es falsch verstanden. Ich dachte, Sie sagten, es sei nicht sinnvoll, Fehler-IDs irgendwo zu platzieren.
Matthew Flaschen

Kein Problem, das heißt nur, meine Antwort war nicht klar genug. :)
fejd

2

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.


Ich vermute, dass kommentierter Code vom SCM überprüft und nicht einmal festgeschrieben werden sollte ... Es fügt dem Code Unordnung hinzu, nur um 5 Minuten in der SCM-Historie zu suchen, wenn Sie ihn eines hypothetischen Tages in der Zukunft brauchen zurück.
Julien Roncaglia

Einverstanden, aber versuchen Sie, dies in sourcesafe umzusetzen: D In unserem Projektteam haben wir mit Überprüfungen gearbeitet, daher werden diese Blockierungen vorerst vom Überprüfer abgelehnt.
Refro

Oh SourceSafe ... Entschuldigung für Sie und Ihr Team.
Julien Roncaglia

Sei nicht, es ist besser als nichts. Und im Moment werden alle Neuentwicklungen mit Subversion durchgeführt, so dass ich jeden Monat weniger mit sourcesafe zu tun habe.
Refro

1

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.


1

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.

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.