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?
Antworten:
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.
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.
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.
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).
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.
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.
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.