Wenn jemand sagt, ein Kommentar füge keinen Wert hinzu, würde ich fragen: für wen?
Persönlich habe ich nie viel von dem Ratschlag gehalten, dass das Schreiben offensichtlicher Kommentare schlechte Praxis ist – wahrscheinlich, weil ich die ganze Zeit offensichtliche Kommentare schreibe.
Jim zeigte einige Beispiele von „Code-Kommentaren, die die gleiche Detailtreue aufweisen wie der Code selbst.“ Das sind die schwierigsten Entscheidungen bei Code-Kommentaren.
// this function adds two numbers
function add(a, b) {
return a + b;
}Es ist einfach, das als nicht nützlich zu bezeichnen. Ich neige dazu, diese Art von Kommentaren nicht zu hinterlassen, aber es ist fair, dass Jim das in Frage stellt. Kommentare können für eine breite Palette von Personen verwendet werden, die irgendwann mit diesem Code interagieren, also warum sollte man sie einschränken?
[…] Kommentare können einen ganz anderen Zweck erfüllen, wenn sie gelesen werden, im Vergleich dazu, wenn sie geschrieben werden. Das sind fast zwei verschiedene Arten von Aktivitäten.
Ich würde hinzufügen, dass sie einen anderen Zweck erfüllen, wenn man alten Code noch einmal durchgeht, im Vergleich zur aktiven Arbeit. Auch anders, wenn man einen Code-Review durchführt, im Gegensatz zur direkten Mitarbeit.
Ich habe es immer gehasst, wenn jemand darauf hinwies, dass ich zu viel kommentiere. Mein Ziel ist es, Code zu schreiben, den jeder mit beliebiger Fähigkeit lesen, verstehen und/oder daraus lernen kann. Wenn ich ein Projekt verlasse, möchte ich es in einem Zustand hinterlassen, den ein Junior-Entwickler verstehen kann.
Es ist einfach, einen Kommentar mit 15 Jahren Erfahrung zu lesen, aber ich habe festgestellt, dass neue Leute Anleitung brauchen. Diese offensichtlichen Kommentare sparen viel Frustration.
Wenn Sie eine komplizierte Bedingung haben,
if (A && B && (C || !D)) { ..., könnten Sie einen Kommentar hinzufügen, der besagt// prüfe <komplexe Eigenschaft> von <Ding>. Oft ist dies ein Zeichen dafür, dass es sinnvoll ist, die Logik in eine Funktion/Methode zu abstrahieren;dingHatKomplexeEigenschaft = (A, B, C, D) => (A && B && (C || !D)). Auf diese Weise liest sich Ihre Bedingungif(dingHatKomplexeEigenschaft(A, B, C, D)) {...und macht den Kommentar überflüssig (neben anderen potenziellen Vorteilen).Etwas wie
add(a: number, b:number): numberist in Typescript perfekt selbsterklärend – in JS benötigen Sie möglicherweise mehr Ausführlichkeit, aber dann istaddNumbers(a,b)viel besser, da dies an den Aufrufstellen offensichtlich wird und somit keinen Kommentar rechtfertigt.Meine Faustregel für Inline-Code-Kommentare ist, dass sie nicht erklären sollten, was der Code tut – man kann gut geschriebenen Code lesen, um zu sehen, was er tut. Wenn ich einen Inline-Code-Kommentar schreibe, erkläre ich damit das Warum – nicht das Was. (Es sei denn, der Code ist zu komplex oder unleserlich – in diesem Fall ist das wirklich ein Grund zum Refactoring, nicht für Kommentare.)
Ich verfolge den gleichen Ansatz bei Commit-Logs: Erkläre nie, was du geändert hast – der Diff wird zeigen, was; erkläre stattdessen, warum du es geändert hast.
Ich bin großzügig mit „Warum“-Kommentaren, es geht mir also nicht darum, die Zeilenanzahl niedrig zu halten – es geht darum, dass Kommentare, wenn ich sie hinzufüge, die bereits vorhandenen Informationen ergänzen sollten. Wenn Sie Kommentare schreiben, die nur andere Informationen wiederholen, verwässern oder verwirren Sie nur die Informationen; Sie bringen dem Leser bei, Ihre Kommentare zu ignorieren.
Vor Jahren schlug ich (teilweise im Scherz) vor, dass ein Maß für die „Lesbarkeit“ durch Zählen der Anzahl der Schluckaufe oder Stockungen im Lesefluss einer Person beim Lesen des Codes bestimmt werden könnte – das heißt, jedes kurze Zurückblicken oder Innehalten zu zählen, bei dem der Leser eine Zeile erneut prüft oder überprüft, um zu bestätigen, dass sie richtig verstanden wurde. Je weniger man das tun muss, desto besser lesbar ist der Code. Beim Lesen von Code mit eingebetteten Kommentaren könnte man argumentieren, dass das Hin- und Herspringen zwischen // Zeilen, die eindeutig Kommentare sind, die zu Code-Segmenten gehören, und unkommentierten Segmenten, die selbsterklärend sind, inhärent weniger lesbar ist, da es zu Stockungen im Lesefluss führt. Ich sage nicht, dass es gut oder schlecht ist oder ob es mir gefallen würde oder nicht, aber ich sage, dass man ein Argument dafür vorbringen kann.