Direkt zur Navigation | Direkt zum Inhalt



// Kommentare im Code

// Kommentare im Code

In dem Artikel „Verwenden Sie keine Verneinung nicht!“ schreibt Stephan Schmidt: „Wenn ich es schaffe, eine if-Anweisung zu vermeiden, dann versüßt mir das immer meinen Tag.“ Ganz ähnlich geht mir das mit Kommentaren. Nicht, dass ich Kommentare im Quelltext per se für eine schlechte Sache halte. Es gibt kaum etwas Hilfreicheres als ein gut platziertes Kommentar. Allerdings gibt es auch kaum etwas Schlechteres als veraltete Kommentare, die den Quelltext unötig aufblasen, den Leser falsch informieren und in die Irre führen.

Software wird ständig erweitert und angepasst. Aufgrund mangelnder Disziplin und der Hektik im Projektalltag gilt dies in der Regel allerdings nicht gleichzeitig für Kommentare. Je älter ein Kommentar ist, desto höher ist die Wahrscheinlichkeit, dass es nicht mehr dem aktuellen Verhalten der Software entspricht.

Wann handelt es sich um ein schlechtes Kommentar?

Neben dem häufigen Grund, dass Kommentare veraltet sind, gibt es auch ein paar weitere Beispiele, die ich euch nicht vorenthalten möchte.

Positionsmarkierungen
Postitionsmarkierungen sind Kommentare, die größere Abschnitte im Code in einzelne kleinere Teile trennen. Anstatt Code durch Kommentare zu separieren, sollten die jeweiligen Abschnitte besser als eigenständige Methoden extrahiert werden.

// **** Form Upload ****
....
// **** Input Validation ****
....

Auskommentierter Code
Ein großer „Freund“ bin ich vor allem von auskommentiertem Code. Nicht nur, dass die Aussagekraft von auskommentiertem Code gegen null geht. Schlimmer ist, dass jeder weitere Entwickler, der über diesen Code stößt, denken wird, dass dieser aus einem bestimmten Grund überlassen wurde. Mit der Zeit verändert sich der umliegende Code und das Kommentar verliert immer mehr an Bedeutung und führt einzig und allein zu Verwirrungen.

In der heutigen Zeit wird jeder Stand bei größeren Software-Projekten mit Hilfe von Versionsverwaltungssystemen wie Subversion, Git oder CVS gesichert. Wird eine bestimmte Funktionalität nicht mehr benötigt, sollte diese schlicht weg gelöscht werden. Mit einem aussagekräftigen Kommentar im Versionsverwaltungssystem, erklärt sich auch viel besser aus welchem Grund diese Funktionalität entfernt wurde.

Redundante Kommentare
Kommentare, die nichts weiter aussagen als der beschriebene Code selbst.

/**
 * Get the car
 */
public Car getCar() { return car; }

/** The name */
private String name;

Gibt es auch sinnvolle Kommentare?

Wie bereits geschrieben halte ich nicht alle Kommentare für unnötig und schlecht. Zum Ausgleich daher auch einige Beispiele für den sinnvollen Einsatz von Kommentaren.

@todo-Kommentare
Die meisten IDEs unterstützen Entwickler durch die Erkennung von @todo-Kommentaren im Code. Werden diese nicht nur als Ausrede verwendet, um unsauberen Code liegen zu lassen, ist der Einsatz solcher Kommentare auf jeden Fall in Ordnung.

Informative Kommentare
Sinnvoll finde ich auch Kommentare, die Informationen zum Kontext des Quelltext liefern. Wurde der Code beispielsweise durch einen Bugfix auf eine ungewöhnliche aber erforderliche Weise angepasst, ist es ratsam die entsprechende Stelle mit einem Kommentar zu versehen.

Kommentare in öffentlichen APIs
Eine gut dokumentierte öffentliche API ist für Entwickler ein Segen. Allerdings gilt diese Aussage nur, sofern die Dokumentation auf aktuellem Stand gehalten wird und dem Entwickler zusätzliche Informationen bietet. Kommentare für Setter und Getter halte ich auch in öffentlichen APIs für unnötig.

Kommentare

Rüdiger Plantiko
Dienstag, 23.03.2010 (8:36)

Hallo Holger,

schöner Blog, genau so sehe ich das auch. Ich habe auch „Clean Code“ gelesen, das lange Kapitel zu Kommentaren darin war mir wie aus der Seele gehobelt.

Zu Deinem Punkt „Informative Kommentare“. Kommentare zu Bugfixes sind nicht grundsätzlich gut, sondern ärgern mich fast immer. Z.B. „Geändert von Rita Kimmkorn, Magic Consulting AG, am 20.3.2010″. Oder langatmige Beschreibungen, wie das System sich früher verhalten hat und wie es sich nun verhält. Selbst den Verweis auf die ID eines begleitenden Defects im Quality Center ist überflüssig.

Für all dieses gibt es die Versionsverwaltung. In der Versionsverwaltung steht eine Textzeile, die mit einem Satz ausdrückt, was die Korrektur beinhaltete, sowie die Defect-ID für nähere Informationen zum Umfeld (welche Personen waren dran, Beschreibung des Fehlersymptoms, Korrekturnummer mit allen in der Korrektur enthaltenen Codeteilen, Beschreibung der Korrektur durch den Entwickler, etc.)

Im Quelltext will ich bestenfalls positive Beschreibungen davon sehen, wie der Code sich verhält, wenn es schon nicht gelingt, ihn selbsterklärend hinzuschreiben (warum übrigens nicht?).

Ich will nicht wissen, wie der Code sich früher einmal verhielt, was für Benutzerprobleme es gab, in was für einen Fehler frühere Codezeilen gelaufen sind, nicht einmal, dass diese Codezeile durch einen Bugfix Nr. SoUndSo geändert wurde.

Gruss,
Rüdiger
All das stört nur beim Lesen des Designdokuments namens Code (sehr schön ist die Philosophie von „Code als Design“ von Jack W. Reeves in einem mittlerweile klassischen Artikel beschrieben: http://www.developerdotstar.com/mag/articles/PDF/DevDotStar_Reeves_CodeAsDesign.pdf ).

Neues Kommentar