Ist es empfehlenswert, mit der Ausgabenummer zu kommentieren?

18

Ich habe viele Ausgabenummern aus Kommentaren von jQuery-Code gesehen . (Tatsächlich gab es im jQuery-Code 69 Problemnummern.) Ich denke, es wäre eine gute Praxis, aber ich habe noch nie Richtlinien gesehen.

Wenn es sich um eine gute Praxis handelt, welche Richtlinien gelten für diese Praxis?

Sanghyun Lee
quelle

Antworten:

22

Im Allgemeinen würde ich es nicht als gute Praxis betrachten. Aber in Ausnahmefällen kann es sehr nützlich sein, wenn der Code etwas Unintuitives tun muss, um ein komplexes Problem zu beheben, und ohne jede Erklärung besteht die Gefahr, dass jemand diesen seltsamen Code "reparieren" und damit brechen möchte Während die Begründung erklärt wird, würde dies zu einem riesigen Kommentar führen, der Informationen aus dem Problem dupliziert.

Michael Borgwardt
quelle
+1 Dies scheint bei den Kommentaren zum jQuery-Problem der Fall zu sein. - Keine Kommentare hier zu haben, wäre ernsthaft verwirrend.
Konrad Rudolph
1
Ich persönlich beziehe mich nur dann auf Probleme im Code, wenn der Code eine Problemumgehung für ein Problem im Code eines Drittanbieters behandelt. Verweise auf Ihren eigenen Issue Tracker gehören zum Versionskontrollsystem, nicht in den Code. Für eine große Codebasis kann es sinnvoll sein, ähnliche Verweise auch für interne Problemumgehungen zu verwenden.
Mikko Rantalainen
14

Ich denke, es reicht aus, die Problemnummer in die Festschreibungsmeldung aufzunehmen, wenn Sie die entsprechende Korrektur in Ihr Quellcodeverwaltungssystem übernehmen.

Beispielsweise:

Fehler Nr. 203: Bei Datenbankverbindungen tritt nach 30 Sekunden kein Timeout mehr auf.

Ich finde, dass das Hinzufügen von Ausgabenummern, Entwicklernamen oder Datumsangaben, an denen Änderungen im Code vorgenommen wurden, nur die Codebasis verschmutzt und von Ihrem Versionsverwaltungssystem wirklich extern verwaltet werden sollte.

Bernard
quelle
Ich denke, du hast recht. Warum setzen jQuery-Committer Ihrer Meinung nach die Ausgabenummern in die Kommentare? Vielleicht ist es ein Sonderfall für populären Code?
Sanghyun Lee
6
Ich stimme dir nicht zu. In Kommentaren wird erklärt, warum der Code so ist, wie er ist, obwohl dies aus dem Code selbst nicht ersichtlich ist. Fehler können einen tollen Kontext für das "Warum" von Code bieten, daher kann ein Link zu einem Fehler sehr hilfreich sein, um ihn zu verstehen. Allerdings mag ich auch Links zu Fehlertickets in Versionsverwaltungsprotokollen, aber das dient einem anderen Zweck.
Jeroen
Ich denke, Sie sollten beides tun, aber ich denke nicht, dass es alleine ausreicht, um diese Kommentare in die Quellcodeverwaltung einzufügen. Sie sehen diese Kommentare nur selten, wenn Sie danach suchen. Wenn diese Referenzen besser sichtbar sind, kann dies eine nützliche IMO sein.
Benjamin Wootton
1
Jeroen: Ich bin wieder anderer Meinung. Das heißt, wenn die Behebung des Fehlers ein schneller und hässlicher Hack ist, sollten Sie dies kommentieren und den Fehler erneut melden. Wenn es sich bei dem Fix um einen korrekten Fix handelt, sollte er tatsächlich erklären, warum er so ist, wie er selbst ist. Im Idealfall sollte es keinen Grund für einen Kommentar jeglicher Art geben, und ein Verweis auf den Fehler in der Quellcodeverwaltung ist ausreichend. Wenn Ihr Fix nicht selbsterklärend ist, müssen Sie eine Umgestaltung in Betracht ziehen.
Martiert
Wenn es sich um eine Implementierung und nicht um einen Fehler handeln würde, würde kein Kommentar angezeigt. Warum? Da die Entwicklung des Codes normal ist und sogar erwartet wird, verweist die Implementierung eines Features nicht auf seine Task-ID, es sei denn, es wurden besondere Umstände festgestellt, im Gegensatz zur Fehlerbehebung, die dazu dient, zur Behebung von Problemen schnell nennenswerte Unterschiede zum Original zu finden. Andernfalls könnte sich ein Programmierer, der sich den Code ansieht, eine Stunde lang am Kopf kratzen, um zu verstehen, warum dies im Vergleich zum Rest des Codes anders gemacht wurde (und es im schlimmsten Fall wieder ändern).
Neil
7

Ich bin mit den anderen Plakaten hier überhaupt nicht einverstanden!

Codekommentare mit Verfolgungsverweisen können eine große Hilfe für die Wartungsprogrammierung sein.

Wenn ich einen Fehler aufspüre und mich dem Bereich des Codes annähere, ist es ein Geschenk Gottes, zu sehen, dass er kürzlich geändert wurde und eine Verknüpfung zum Kontext der Änderung besteht.

Ja, wir haben Quellcodeverwaltung, aber es kann sehr langsam sein, Dateien und Module einzeln zu überprüfen. Sie möchten, dass diese Dinge Sie für die letzten Änderungen herausspringen.

Ich würde sie wahrscheinlich ablehnen, da ich wirklich alte in der Codebasis sehe, aber es gibt sehr wenig Nachteil, neuere in und viele potenziell eingesparte Entwicklerzeit zu behalten, wenn Sie sie intelligent verwenden.

Ich denke tatsächlich, dass diese kleinen Verweise auf Ihr Fehlerverfolgungssystem detaillierten Kommentaren im Code vorzuziehen sind.

Benjamin Wootton
quelle
2
Wenn Sie ein Quell- / Versionscodesystem verwenden, das sich lohnt, kann Ihr Versionskontrollsystem jede Codezeile mit der geänderten Revision versehen. Beispielsweise bietet der Standard git gui blame <filename>eine sehr schnelle Benutzeroberfläche zum Durchsuchen des Codeverlaufs, wenn Sie git verwenden. Die Verwendung eines Tools zum Kombinieren von Codekommentaren mit dem Verlauf ermöglicht eine wesentlich bessere Dokumentation des Codes als dies bei Inline-Kommentaren jemals der Fall ist. Das heißt, wenn Sie sich die Mühe machen, gute Festschreibungsnachrichten zu schreiben (eine gute Festschreibungsnachricht sollte in etwa einer E-Mail-Nachricht entsprechen, in der erläutert wird, warum dieser Patch angewendet werden sollte).
Mikko Rantalainen
Wenn Sie ein Projekt mit einem Bug-Tracker von Grund auf neu starten, stammen praktisch alle Codezeilen aus einer User Story oder einer Fehlerbehebung. Was dann? Kommentieren Sie alle Zeilen?
GabrielOshiro
5

Wenn Sie eine Richtlinie für "Clean Code" abonnieren, müssen Sie sich wahrscheinlich fragen, ob das Hinzufügen von Kommentaren überhaupt empfehlenswert ist. Wenn der Code nur mit einem Kommentar geklärt werden kann, fügen Sie einen hinzu. Andernfalls sollten Sie in der Lage sein, die Funktionsweise Ihres Codes einfach durch Lesen zu verstehen (vorausgesetzt, Sie verwenden sinnvolle Namen für Ihre Variablen, Methoden usw.).

Unabhängig von Ihrer persönlichen Meinung darüber, ob das Kommentieren eine gute Praxis ist oder nicht, sollte ein Kommentar Informationen enthalten, die für den Code, auf den sich der Kommentar bezieht, von direktem Wert sind. In diesem Fall stellt sich die Frage, ob das Hinzufügen einer Ausgabenummer dem Code einen Mehrwert verleiht. Das Problem, das ich beim Hinzufügen der Problemnummer sehe, besteht darin, dass Sie möglicherweise einen Codeabschnitt haben, der stark geändert wird, um mehrere Probleme zu lösen. Nach einer Weile ist es möglicherweise nicht mehr möglich, die Änderungen zu identifizieren, die sich auf ein bestimmtes Problem beziehen. Bei nachfolgenden Problemen muss möglicherweise der Code für frühere Probleme stark überarbeitet werden. Dies ist vielleicht ein extremes Beispiel, es zeigt jedoch, wie sich die Ausgabenummern in Kommentaren im Code als ziemlich nutzlos herausstellen können.

Wenn Sie garantieren könnten, dass die Situation, die ich gerade beschrieben habe, niemals eintreten würde, würde ich dennoch argumentieren, dass die Problemnummer selbst ohne eine Beschreibung des Problems immer noch ziemlich nutzlos ist, und dennoch gehören all diese Informationen wirklich in Ihre Issue-Tracking-System und sollte dupliziert werden müssen. Ein besserer Ort, an dem Sie die Nummer des Problems notieren können, ist Ihr Versionskontrollsystem als Commit-Kommentar. Der Vorteil besteht darin, dass Sie Versionen vergleichen und die Codeänderungen in Bezug auf ein bestimmtes Problem anzeigen können, während die Problemnummer selbst die erforderliche Kennung angibt, wenn Sie den Grund für die Änderung des Codes überprüfen möchten.

In Anbetracht dessen würde ich vorschlagen, dass das Hinzufügen von Ausgabenummern zu Kommentaren in Ihrem Code keine gute Vorgehensweise ist.

S.Robins
quelle
4

Ich denke, es ist eine gute Praxis, sich auf ein Thema zur weiteren Lektüre zu beziehen, während Sie im Kommentar selbst eine kurze Erklärung geben.

Im Allgemeinen füge ich nur Kommentare hinzu, wenn der Code etwas Subtiles oder Unintuitives enthält. Da einige subtile Probleme nicht in wenigen Zeilen vollständig erklärt werden können und ich nicht Dutzende von Kommentarzeilen hinzufügen möchte, möchte ich einen kurzen Kommentar hinzufügen, der beschreibt, was damit erreicht werden soll, und auf das Problem für verweisen Einzelheiten.

Beispielsweise:

// Verify MAC before checking the padding, to avoid padding oracle attacks
// See issue 123 for details

Wo Ausgabe 123 beschreibt, wie dieser Angriff aussehen könnte und warum der neue Code immun gegen den Angriff ist.

Oder:

// Using foo's algorithm here, since it fits out usage pattern best
// Check issue 345 for a discussion of possible algorithms, and why foo was chosen.

Das Hauptproblem beim Einfügen von Ausgabenummern in Ihre Quelle besteht darin, dass Sie jetzt einen externen Verweis haben. Sie müssen also sicher sein, dass Sie das Problem nicht verlieren.

CodesInChaos
quelle
0

Das Einfügen der Issue-Nummer in Commit-Nachrichten kann sehr nützlich sein, wenn Ihr Quellcode mit kontinuierlicher Integration verknüpft ist. Anwendungen wie TeamCity ziehen diese Informationen heraus und ermöglichen eine bessere Berichterstattung.

Mit dem oben Gesagten bin ich mir nicht 100% sicher, ob es sich um Code-Kommentare handelt. Das Einfügen von Ausgabenummern in den Code funktioniert gut, wenn die Ausgabenummern beibehalten werden (z. B. wenn Sie die Ausgabenverfolgung nicht ändern) und für ein bestimmtes Projekt nicht viele Ausgaben vorliegen.

Es ist wahrscheinlich hilfreicher, wenn Sie das Problem und die Lösung beschreiben, damit der nächste Entwickler die Problemnummer nicht nachschlagen muss. Der Compiler oder Minifier entfernt nur Ihre Kommentare, bevor der Code veröffentlicht wird, sodass sich dies nicht auf das Endergebnis auswirken sollte.

Skyler
quelle