Kommentare sind schlecht

Zu Beginn zunächst ein Zitat aus Clean Code (Seite 86)

Die Wahrheit kann nur in einer Stelle gefunden werden: Im Code. Nur der Code kann wirklich sagen, was er tut. Er ist die einzige Quelle für wirklich genaue Informationen. Deshalb sollten wir uns anstrengen, Kommentare [...] zu minimieren.

I disagree. Und zwar completely. Ich erklär' auch gleich, warum.

Ok, das obige Statement wird wenig später relativiert, insbesondere wird auch auf "gute" Kommentare eingegangen, zu denen auch "Erklärung der Absicht" (erleichtertes Aufatmen) und "Klarstellungen obskurer Konstruktionen" (dito) gehört. Dennoch bleibt beim Leser haften, daß Kommentare irgendetwas Anrüchiges haben. Das aber halte ich mindestens für bedenklich. Warum denn nun aber?

don't forget! Schlechte Kommentare beschreiben, was der Code macht. Das ist ganz offensichtlich grober Unfug und verschwendet in der Tat nur die Zeit des Lesers. Solche Kommentare gehören daher wirklich auf den Müll. Soweit gehe ich völlig konform.

Gute Kommentare

Gute Kommentare hingegen beschreiben den Code auf einer Meta-Ebene. Man kann leider eben nicht alles sinnvoll mit Erklärbär-Code abdecken, auch wenn man sich noch so sehr bemüht. Das scheitert bereits an zwei simplen Tatsachen. Erstens wird ein Methodenname wie jeder andere Text immer durch den Leser vor dessen eigenem Erfahrungs- und Wissenskontext interpretiert und somit durch die persönliche Brille wahrgenommen. Je knapper eine Benennung ist (und üblicherweise ist das bei Methoden- oder Variablennamen der Fall), desto größer auch die Gefahr einer Fehlinterpretation.

Sinnvolle Kommentare liefern Meta-Informationen

Zweitens ist es auch bei bestmöglichster Benamsung aller Bestandteile nicht immer erschöpfend möglich, alle relevanten Aspekte eines konkreten Implementierungsdetails in der Benennung unterzubringen. Das gilt umso mehr, als auch richtig treffende Bezeichnungen immer noch Spielraum für Interpretationen (und damit Unsicherheit) bieten können.

Erfahrungsgemäß tun sich viele Entwickler damit schwer, Variablen oder Methoden nicht nur mit korrekten, sondern auch noch auf Anhieb verständlichen Namen zu versehen. Wer beispielsweise auf der Suche nach einem Bug ist, der weiß Kommentare zu schätzen, die Informationen darüber liefern, was die Intention für den Code war, was der Code also machen sollte, wenn er korrekt implementiert wurde.

Gute Kommentare sind wertvoller Bestandteil des Codes.

Solche Kommentare sind ein unschätzbares Hilfsmittel bei der Frage, ob beispielsweise schon der Lösungsansatz für ein gegebenes Problem unbrauchbar ist, ob vielleicht eine ungeeignete Routine aufgerufen oder ob einfach nur eine fehlerhafte Implementierung in einem Grenzfall vorliegt, der durch die vorhandenen Testfälle bisher nur noch nicht erfaßt wurde. Ohne die Zusatzinformationen, die ein guter Kommentar liefern kann, fällt diese Unterscheidung manchmal sehr, sehr schwer.

Weiterhin kann ein solcher Kommentar bereits dem Verfasser selbst helfen, seine Routine nochmals gedanklich auf etwaige kritische Grenzfälle oder Ungenauigkeiten in der Implementierung oder der Schnittstelle nach außen hin abzuklopfen.

Zu allem Überfluß kann auch der Code selbst, die (Zitat) "einzige Quelle für wirklich genaue Informationen" auch mal falsch sein kann - wer hätte das gedacht? Da stehen wir also, mit unserer unbrauchbaren "Quelle für genaue Informationen", mitten in einer unkommentierten Codewüste, mit halbgaren Methodennamen, und der Urheber des Codes ist letzte Woche auf seine lang geplante Weltumsegelung aufgebrochen und schippert gerade irgendwo mitten auf dem Ozean herum ...

Kommentare als Teil des Quellcodes betrachten

Problematisch - und hier stimme ich wieder zu - ist es auf jeden Fall, wenn Kommentare verrotten, weil sich der umgebende Code geändert oder verschoben hat, neue Teile eingefügt wurden oder die Routine inzwischen komplett umgeschrieben wurde. Hier ist eben die Disziplin erforderlich, Kommentare als wesentlichen Bestandteil des Codes anzusehen.

Nachtrag: Ideale Welt versus existente Realität

Mir sind zwischenzeitlich mehrfach Thesen über den Weg gelaufen, in denen postuliert wird, daß Kommentare überflüssig wären, wenn der Code exakt nach allen Regeln der Kunst - hier wurde insbesondere Clean Code genannt - geschrieben worden wäre. Eigentlich erübrigt sich schon fast jede Gegenargumentation, denn man erkennt bereits am flächendeckenden Einsatz von Konjunktiven, daß die Sache in der Praxis wohl doch nicht ganz so einfach sein kann. Tatsächlich kann sich der Ansatz, der in der Theorie so einleuchtend und zeitsparend klingt, in der Praxis aus diversen Gründen eher als kontraproduktiver Zeitfresser denn als echter Gewinn entpuppen:

Schon einem geübten Clean-Coder gelingt es nicht immer auf Anhieb, seinen Methoden, Klassen und Variablen aussagekräftige Namen zu geben, die sofort und im ersten Anlauf über jeden Zweifel erhaben sind. Die ganze Theorie steht und fällt aber gerade mit dem Vorhandensein einer ausreichend wasserdichten Benamsung der Einzelteile und Algorithmen.
Die wenigsten Entwickler sind geborene Clean-Coder, die vom ersten Tag ihres Schaffens sofort lupenreinen Code fabrizieren. Denen wird es um so schwerer fallen, das notwendige Qualitätslevel zu ereichen. Sicher, das ist lediglich eine Frage von Ausbildung und Erfahrung, aber so etwas kommt eben nicht über Nacht.
Das Weglassen des Kommentares mit der Begründung "steht doch alles im Code" führt dazu, daß der lesende Entwickler den Code tatsächlich lesen und analysieren muß. Die Zeit, die der ursprüngliche Entwickler mit dem Weglassen des Kommentares 1x eingespart hat, legt also später jeder einzelne der N Leser wieder drauf. Abgesehen von diesem fragwürdigen Effizienz-Verständnis muß sich der Leser auf einer vergleichsweise niedrigen Abstraktionsebene mit dem Code beschäftigen, statt auf sich auf das konzentrieren zu können, was er eigentlich tun will.

Womit wir wieder bei Clean Code ankommen, denn SLA (Single Level of Abstraction) ist zu Recht eine Tugend. Und was für den Aufbau von Methoden, Klassen, Layern gilt, sollte auch für die Kommentierung des Codes gelten: Liefere Informationen auf höherem Level, dokumentiere die Absicht und das Prinzip. Mache deinen Kollegen die Wartung, Weiterentwicklung und Verwendung deiner coolen Komponente und deines genialen Algorithmus so einfach wie möglich. Sie werden es dir danken.