Kommentare können auch schädlich sein, nämlich dann, wenn sie falsch sind und ihre Leser auf zeitraubende Irrwege führen. Selbst sinnvolle Kommentare bringen zusätzliche Arbeit mit sich: In Zukunft wird man nicht nur den Code überarbeiten müssen, sondern auch den zugehörigen Kommentar. Wer schon ahnt, dass er sich dazu nicht immer aufraffen wird, der sollte sich beim Schreiben von Kommentaren fragen: »Kann ich diese Information aus dem Kommentar in den Code verschieben?«
Oben haben wir insbesondere Einsteigern in die Programmierung empfohlen, etwas mehr zu kommentieren, als eigentlich nötig wäre. Folgt man diesem Rat, dann ist es noch wichtiger als sonst, Kommentare rücksichtslos zu löschen, wenn sie überholt oder falsch sind. Viele Entwickler haben Scheu davor, Code zu löschen, weil seine Erstellung immerhin mit Mühe verbunden war. Diese Haltung überträgt sich auch auf Kommentare, sie ist aber falsch.
Überholte Codekommentare, die den Stand von gestern dokumentieren, sind schlechter als keine. Wenn Sie nicht die Zeit finden, einen Kommentar nachzuziehen, dann versehen Sie ihn zumindest mit einem TODO und einer kurzen Erklärung dazu, warum er veraltet ist. Wenn er wirklich überflüssig geworden ist, löschen Sie ihn. Gute Programmierer sind ziemlich rücksichtslos im Löschen von Code und noch rücksichtsloser im Entfernen von Kommentaren, weil sie wissen, dass sie notfalls immer zurück können, etwa indem sie einen alten Stand aus dem Versionskontrollsystem zurückspielen oder mit überschaubarem Aufwand neu schreiben.
Weitere Anzeichen für Kommentarprobleme sind:
jede nicht ganz triviale Funktion sollte am Anfang mit ein oder zwei beschreibenden Sätzen ausgestattet werden. Wenn man mehr als diese Sätze benötigt, stimmt etwas mit der Funktion nicht. Vermutlich will sie zu viel auf einmal oder ist überkompliziert angelegt.
Sie haben mit einem Refactoring-Tool den Namen einer Klasse, Funktion oder Variable geändert, Ihr Tool hat die Kommentare aber nicht berücksichtigt. Im Kommentar trägt das geänderte Element jetzt noch den alten Namen. An sich ist es nicht falsch vom Refactoring-Tool, die Kommentare zu ignorieren, denn es kann ja sein, dass Sie eine sehr schlampig benannte Variable namens variable haben, die Sie eines Tages beim Aufräumen entdecken und in timestamp umbenennen. Dann würde es große Verwirrung stiften, wenn jedes Auftauchen des Worts variable in den Kommentaren ebenfalls durch timestamp ersetzt würde. In vielen Entwicklungsumgebungen gibt es die Option, beim Refactoring die Kommentare mitzuberücksichtigen.
Wie bei Variablennamen (siehe Kapitel 5) gilt auch hier: Verwenden Sie Abkürzungen nur dann, wenn die Abkürzung gebräuchlicher ist als die ausgeschriebene Version HTML«, »PDF«).
Wer einen Bug behoben hat und ein Versionskontrollsystem verwendet, steht vor der Frage: Wohin gehört der Kommentar, in den Code oder in die commit message? In der Regel ist es sinnvoll, zusammen mit dem Commit nur zu vermerken, was geändert \urde. Gut organisierte Projekte verwenden ein Aufgaben-Tracking-System wie Jira und erlinken die commit message mit der zugehörigen Task-ID, damit man den Hintergrund einer Änderung auch später noch nachvollziehen kann. Betreibt man ein weniger gut rganisiertes Projekt, schreibt man die Begründung für die Änderung als Kommentar in . n Code selbst. Das ist nicht ganz so günstig, weil die lange Vorgeschichte den Code rgendwann schwer lesbar macht.
Denken Sie sehr genau über die Voraussetzungen fürs Verständnis nach, wenn der Code • an Nicht- oder Seltenprogrammierern angefasst werden könnte. Das ist zum Beispiel dann der Fall, wenn Sie der Welt ein WordPress-Plugin, ein Browser-Add-on oder ein Gr»-' : - - ' zur Verfügung stellen, oder wenn die Nutzer Ihres Codes vor der
_ nbetriebnahme noch irgendwelche Zugangsdaten in eine Code-Datei eintragen müssen.
Aus dem Schatzkästlein der Kommentierkunst
• # total_hoiirs_wasted_here =16
• # Now, God only knows
• # to my wife, Darlene
• # drunk, fix later
• # Temporary my ass!
• # please work
• # too scared to delete
• # Dear future me. Please forgive me.
• # it was hard to write so it should be hard to read
• # TODO: Fix this. Fix what?
• # Ruby lexer adapted from irb - The internals are not documented because they are scary.
• # This Code can only be loved by a mother.
• #Was, warum geht das nicht?
Quellen: stackoverflow.com/questions/184618/what-is-the-best-comment-in-source-code-you-have-ever-encounteredl, blogfefe.de/?ts=b2708668, @inoxio I Twitter, @lAmMarth I Twitter.