Ist es in Ordnung, Kommentare zu Fehlerkorrekturen in den Quellcode zu schreiben?

Question

Und wenn ja, wo zeichnest du die Linie? Meine Kollegen und ich stimmen zu diesem Thema nicht überein. Ich habe solche Dinge gesehen, wie

// fixes bug # 22 

zu

// fixed bug: shouldnt be decrementing 
i++; 

Ist es in Ordnung, wenn die Änderung ziemlich signifikant ist, und radikal ändert, was die Methode geschrieben wurde, zu tun? Oder ändern Sie einfach den zusammenfassenden Text der Methode, um zu reflektieren, was es jetzt tun soll?

Meine Meinung ist, dass diese Informationen in die Quellcodeverwaltung eingegeben werden sollten. Einige sagen, dass dies schlecht ist, weil sie dann außerhalb des Kontextes der Quellcodeverwaltung verloren gehen (sagen Sie, dass Sie zwischen Systemen wechseln und historische Daten behalten wollen).

Answer 1

Kommentare sollten erklären, wie die Methoden funktionieren.

Die Quellensteuerung erklärt, warum Änderungen vorgenommen wurden.

Answer 2

Wir hatten ein paar Kommentare wie diese, aber dann starb unser Bugzilla-Server und wir starteten bei Bug # 1, so dass sie alle bedeutungslos sind. Eine kurze Erklärung des Fehlers ist jetzt meine bevorzugte Methode.

Answer 3

Unter der Annahme, Kommentare nicht überflüssig sind (das klassische i++; //increment i Beispiel in dem Sinne kommt), ist es so gut wie nie ein Grund gegen zu argumentieren, um einen Kommentar hinzufügen, unabhängig davon, was auf es bezogen. Informationen sind nützlich. Es ist jedoch am besten, beschreibend und prägnant zu sein - sage nicht "behebt den Fehler #YY", sondern füge etwas hinzu wie "das war früher für x = 0 fehlgeschlagen, die zusätzliche Logik verhindert das". Auf diese Weise kann jemand, der den Code später betrachtet, verstehen, warum ein bestimmter Abschnitt für eine ordnungsgemäße Funktion kritisch ist.

Answer 4

Nein. Sie sollten Informationen über Fehler und den Änderungssatz behalten, der den Fehler außerhalb des Quellcodes behebt. Alle Kommentare im Code selbst sollten sich nur auf den Code beziehen. Alles andere ist nur Unordnung.

Answer 5

Ich persönlich finde, dass Kommentare über den Code selbst sein sollten, nicht über einen Bugfix.

Mein Grund dafür ist Wartbarkeit - 2 (oder 10) Jahre später wird dieser Kommentar nicht mehr sinnvoll sein. In Ihrem Beispiel oben würde ich es vorziehen, so etwas wie:

// Increment i to counteract extra decrement 
++i; 

Der Unterschied besteht darin, dass es nicht zu einem Bug, gebunden ist, sondern vielmehr, was der Code tut. Kommentare sollten den Code kommentieren, nicht Meta-Informationen, IMO.

Diese Meinung ist zum Teil, weil ich eine sehr alte Codebasis halten - und wir haben viele Kommentare, die nicht sinnvoll mehr im Zusammenhang mit Fehlerkorrekturen oder Funktionserweiterung Anfragen, etc ....

Answer 6

ich auf FogBugz verlassen und Eincheckkommentare in SVN. Funktioniert gut, obwohl, wie Jeffaffone sagte, Fallnummern nicht viel Sinn machen, wenn Sie Ihre Fehlerdatenbank verlieren.

Ein Problem mit dem Einfügen von Kommentaren in den Code ist, dass Ihr Code im Laufe der Zeit mit Kommentaren über Probleme, die für eine Weile nicht bestanden haben, übersät ist. Wenn Sie solche Kommentare in die Check-in-Kommentare der Quellcodeverwaltung einfügen, binden Sie effektiv Informationen über den Fix an die spezifische Version, in der sie korrigiert wurden. Dies kann später hilfreich sein.

Answer 7

Meine Ansicht ist, dass Kommentare für die Absicht des Entwicklers relevant sein sollten, oder Highlights von "warum", die den Algorithmus/Methode umgeben.

Kommentare sollten keine Fix-in-Time enthalten.

Answer 8

Hinzufügen eines Kommentars über die Fehlerbehebung ist eine gute Idee, wenn Sie das Richtige schreiben.

Zum Beispiel

/* I know this looks wrong, but originally foo was being decremented here, and 
    it caused the baz to sproing. Remember, the logic is negated by blort! */ 

Sachen wie Fixes bug #22ist besser in der Quellcodeverwaltung gehalten. Kommentare in Ihrem Code sollten Wegweiser sein, um zukünftigen Besuchern auf ihrem Weg zu helfen, Prozesse und Tracking nicht zu befriedigen.

Answer 9

Ich stimme zu, dass solche Daten in der Quellcodeverwaltung oder in einem anderen Teil Configuration Management abgelegt werden sollten. Nachdem ich in Codebasen gearbeitet habe, die Informationen über Fehlerbehebungen in Kommentaren platzieren, kann ich sagen, dass es später zu sehr überladenen Kommentaren und Code führt. Sechs Monate, nachdem der Fix in Kraft ist, willst du wirklich etwas über eine Zeile wissen, die einen lang zurückliegenden Fehler behebt? Was machen Sie mit Kommentaren, wenn Sie den Code umgestalten müssen?

Answer 10

Etwas wie // fixes bug # 22 ist für sich allein bedeutungslos, und erfordert zusätzliche Schritte, um sogar eine Vorstellung davon zu bekommen, was es bedeutet und welche Rolle es erfüllt. Eine kurze Beschreibung ist meiner Meinung nach geeigneter, unabhängig von der Bug-Tracking- oder Source-Control-Software, die Sie verwenden.

Answer 11

Wenn der Algorithmus auf eine bestimmte Art und Weise codiert werden muss - um zB einen Fehler in einer API von Drittanbietern zu umgehen, sollte dieser im Code kommentiert werden, damit die nächste Person, die mitkommt, nicht versucht " optimieren Sie den Code (oder was auch immer) und führen Sie ein Problem erneut ein.

Wenn Sie einen Kommentar hinzufügen, wenn Sie den ursprünglichen Fehler beheben, dann tun Sie es.

Es dient auch als Markierung, damit Sie den Code finden können, den Sie überprüfen müssen, wenn Sie jemals auf die nächste Version der API aktualisieren.

Answer 12

Wir verwenden Team Foundation Server für die Quellcodeverwaltung hier in meiner Firma und können einen Check-in an einen Fehlerbericht binden, also würde ich keinen Kommentar direkt in den Code schreiben, um denselben Zweck zu erfüllen.

Wie auch immer,, in Situationen, in denen ich Code als Workaround für einen Fehler im .NET Framework oder einer Drittanbieterbibliothek implementiere, lege ich die URL in das Microsoft TechNet-Protokoll oder die Website, die das beschreibt Fehler und sein Status.

Answer 13

So offensichtlich

// fix bug #22 
    i++; 

ist nicht ein effektive Kommunikation.

Gute Kommunikation ist meist gesunder Menschenverstand. Sag was du meinst.

// Compensate for removeFrob() decrementing i. 
    i++; 

Fügen Sie die Fehlernummer hinzu, wenn sie zukünftigen Lesern wahrscheinlich hilft.

// Skipping the next flange is necessary to maintain the loop 
    // invariant if the lookup fails (bug #22). 
    i++; 

Manchmal werden wichtige Gespräche in Ihrem Fehlerverfolgungssystem aufgezeichnet. Manchmal führt ein Fehler zu einer Schlüsselerfahrung, die die Form des Codes ändert.

Answer 14

Im Perl5-Quellenrepository ist es üblich, auf Bugs mit der zugehörigen Trac-Nummer in Testdateien zu verweisen.

Das macht mehr Sinn für mich, weil das Hinzufügen eines Tests für einen Fehler verhindert, dass dieser Fehler jemals wieder unbemerkt bleibt.