Sind Quellcodekommentare in Zeiten von agil und Clean Code überhaupt noch nötig?

Eines der agilen Prinzipien lautet: “Funktionierende Software mehr als umfassende Dokumentation”. Viele Entwickler sind daher der Meinung, dass sie überhaupt nichts mehr dokumentieren bzw. im Code kommentieren müssen. Wer im Manifest jedoch weiterliest, erfährt “obwohl wir die Werte auf der rechten Seite wichtig finden, schätzen wir die Werte auf der linken Seite höher ein”. Dokumentation spielt auch in der agilen Softwareentwicklung sehr wohl eine wichtige Rolle. Sie entsteht jedoch nicht mehr im Vorhinein bei Entwurf und Design der Software, sondern erst dann, wenn sich das Softwareprodukt stabilisiert hat.

Auch “Clean Code” wird als einer der Gründe vorgeschoben, um sich voll und ganz in das Programmieren stürzen zu dürfen. “Mein Code ist selbsterklärend, er muss nicht kommentiert werden” – schon oft gehört, fast immer haltlos. Selbst in der Clean-Code-Bibel von Uncle Bob gibt es ein eigenes Kapitel zum Thema Kommentare (“Nothing can be quite so helpful as a well-placed comment.”). Offensichtlich überspringen die meisten Leser dieses Kapitel…

Pro und Contra

Zugegeben: Unsere heutigen Programmiersprachen bieten uns die Mittel, unseren Code ausdrucksstark zu gestalten. In Java haben gibt es hierfür z. B. Packages, Klassen, Interfaces, Methoden, Enums etc. Ein Kommentar kann daher erst einmal als ein Scheitern gesehen werden, sich angemessen mit den Sprachkonstrukten der gewählten Programmiersprache auszudrücken. Aber es gibt immer noch einen berechtigten Anspruch auf Kommentare im Code. Kommentare liefern vor allem den Kontext, in welchem ein Quellcode geschrieben wurde. Sie vermeiden Überraschungen, da sie den Leser wertvolle Zusatzinformationen liefern können, welche nicht über den Quellcode kommuniziert werden können.

Kommentare im Code haben auch Nachteile. Da sie eine Unterart von Dokumentation sind, gelten für Kommentare die gleichen Nachteile wie für Dokumentation:

• Dokumentation ist ein wesentlicher Kostenfaktor, da Dokumentation geschrieben, gepflegt und gelesen werden muss.
• Dokumentation kann an zu vielen Stellen stehen, welche teilweise unbekannt sind.
• Dokumentation veraltet schnell, da sich der Quellcode unabhängig von einer Dokumentation weiterentwickeln kann.
• Zu viel Dokumentation kann dazu führen, Wichtiges vom Unwichtigen nicht mehr unterscheiden zu können.

Es gibt (wie so oft) weder schwarz noch weiß, sondern “es kommt darauf an” von welcher Art von Kommentar geredet wird. Daher die Frage: Welche Art ist sinnvoll und auf welche Art kann gerne verzichtet werden?

Arten von Kommentaren

Rechtliche Informationen

Dies betrifft Kommentare, welche die Lizenz, unter welcher der Quellcode gestellt wird, deutlich machen. Diese Art von Kommentaren ist in vielen Unternehmen vorgeschrieben und auch sinnvoll. Zum Glück sind diese Kommentare gleich und können mit einer IDE auch entsprechend automatisiert in den Header einer Quellcodedatei eingefügt werden.

Informative Kommentare

Kommentare, welche zusätzliche Informationen über ansonsten schwer nachvollziehbare oder unverständliche Quellcodestellen liefern. Die entsprechenden Stellen sind hier jedoch auf Grund der essentiellen Komplexität (also auf Grund der Schwere des zu lösenden Problems) schwer zu verstehen und nicht der akzidentiellen Komplexität (d. h. der eigenen Unfähigkeit, den Code verständlich zu schreiben) geschuldet. Beispielsweise sind dies reguläre Ausdrücke oder spezielle SQL-Anweisungen, mit welchen ein Entwickler nicht jeden Tag konfrontiert wird. Allgemein gilt hier: Bevor sich ein Entwickler nach einer gewissen Zeit (meist reichen hier Tage) wieder in die Problemlösung hineindenken muss, ist ein informativer Kommentar (wenn er nicht durch eine bessere Quellcodestrukturierung ersetzt werden kann) zwingend.

Warnende Kommentare

Warnende Kommentare im Quellcode geben Hinweise darauf, dass bei der Verwendung oder Ausführung des Quellcodes etwas Unerwartetes geschehen kann. Unter Umständen kann dies auch relativ gefährlich sein (z. B. das Löschen eines temporären Verzeichnisses oder das Werfen eines Fehlers beim Methodenzugriff). Daher sind solche Kommentare, welche solche Situationen explizit darstellen, sehr erstrebenswert. Aber: “Gefährlich” agierender Quellcode sollte erst gar nicht vorhanden oder (falls dies nicht geht), standardmäßig abgeschaltet sein.

Public-API-Kommentare

Es gibt für Entwickler nichts Schöneres, als eine gut dokumentierte API (siehe z. B. Mockito oder Pandas). Bestenfalls enthält hier der Kommentar des Quellcodes direkt Verwendungsbeispiele. So wird der Einstieg in eine fremde Bibliothek oder eines unbekannten Frameworks immens erleichtert. Public-API-Dokumentation kostet jedoch auch Zeit und Geld und wird daher für APIs, welche nur innerhalb von Unternehmen verwendet werden, leider – zu Unrecht – vernachlässigt. Der Kosten-Nutzen-Aspekt ist jedoch sehr offensichtlich: 1 Zeiteinheit für das Dokumentieren durch 1 Entwickler gewinnt immer gegenüber n Zeiteinheiten für die ansonsten nötige Einarbeitungszeit in die API von n Entwicklern. Eine gute API-Dokumentation bietet für Unternehmen zudem einen Investitionsschutz, da die Funktionen der Software klar und deutlich festgehalten werden. Die API-Dokumentation sorgt zudem für mehr Codequalität, da durch den Dokumentationsvorgang der vorhandene Quellcode noch einmal zusätzlich durchdacht werden muss. Stellt sich die Dokumentation als schwierige Aufgabe dar, sollte immer geprüft werden, ob nicht der Quellcode zu unverständlich ist und eine Überarbeitung notwendig wird.

Erläuternde Kommentare

Dies sind Kommentare, welche den Aufbau und den Ablauf des Quellcodes beschreiben. Wie oben bereits erwähnt, gibt es hier in jeder einigermaßen modernen Programmiersprache bereits entsprechende Sprachkonstrukte, die genau hierfür geschaffen wurden. Erläuternde Kommentare sind daher ein Indiz für die Unfähigkeit eines Entwicklers, sich nicht angemessen in der Programmiersprache ausdrücken zu können. Diese Ratlosigkeit des richtigen Ausdrückens kann auch ein Hinweis darauf sein, dass etwas mit dem Design nicht passt und hier dringend noch einmal eine Überarbeitung stattfinden sollte. Allgemein sind erläuternde Kommentare eine Rechtfertigung für etwas, was man nicht richtig durchdrungen hat. ABER: Manchmal ist es besser, für unverständliche Codestellen zumindest einen Kommentar über die Absicht des vorliegenden Quellcodes zu haben.

Work-In-Progress-Kommentare

Manchmal soll es in der täglichen Projektarbeit vorkommen, dass keine Zeit für eine 100%ig saubere Umsetzung der Anforderungen vorhanden ist. Was bleibt, sind unvollständig implementierte Funktionen, welche mit entsprechenden Kommentaren wir “TODO: noch nicht ganz fertig…” oder “FIXME: stürzt ab, wenn Variable negativ” versehen sind. Läuft die Ausführung über eine solche, teilweise implementierte Funktion im Code, kommt das nicht nur beim Kunden schlecht an. Diese “Work-in-Progress”-Kommentare sollten dann wenigstens über entsprechende Tags wie “TODO” oder “FIXME” markiert sein und über ein Continuous-Inspection-Werkzeug regelmäßig ausgewertet werden.

Redundante Erklärungen

Dies sind Kommentare, welche einfach das, was schon der Quellcode selbst zeigt, wiederholen (z. B. für die Methode “getBetrag()” gibt es einen Kommentar wie etwa “gibt den Betrag”). Ein Kommentar sollte immer etwas zum kommentierten Code zusätzlich beitragen. Ist dies nicht der Fall, fehlt der Mehrwert und der Kommentar ist daher überflüssig. Die schlimmste Stufe sind hier autogenerierte Kommentare (z. B. für das Attribut “private Betrag betrag” der Kommentar “/* The betrag */”. Einfach nur traurig…). Sollten Entwickler gezwungen sein, solche Kommentare auf Grund einer Dienstanweisung o. ä. zu verfassen, muss hier sofort aktiv gegengesteuert werden! Solche Kommentare erzeugen ansonsten nur ein unnötiges Grundrauschen, unter dem wichtigere Kommentare untergehen.

Frustkommentare

Kommentare, welchen die Unzufriedenheit von Entwicklern aufzeigen (z. B. “liest das hier jemand” oder “yak, schon wieder ein Serviceaufruf”). Diese Kommentarart dokumentiert aber auch die Zweifel an der Richtigkeit der Vorgaben oder des Umgesetzten. Dies kann Kritik an der vorhandenen Architektur oder dem Sinn von Vorgaben sein. Professionelle Softwareentwickler kommunizieren solche Themen klar und deutlich beim Produktverantwortlichen. Hier sollten sie dann auch entsprechende Gründe für den Status Quo geliefert bekommen (außer es wurde aus “politischen Gründen” so entschieden, dann muss dies nur offiziell dokumentiert werden!). Noch ein Hinweis: Entwickler committen all ihre Kommentar über ein Versionskontrollsystem in den Quellcode, der für viele weitere Personen sichtbar ist. Jeder kann hier nachsehen, wer den Frustkommentar verfasst hat.

Spaßkommentare

Ähnlich wie Frustkommentare, stören Kommentare, welche nur zur vermeintlichen Belustigung der nachfolgenden Entwickler verfasst wurden, bei der täglichen Arbeit. Allein die Vorstellung, bei einem extrem wichtigen Bugfix-Vorhaben erst einmal über ein paar (womöglich eigene) Spaßkommentare hinwegzulesen, sollte den Spaß an Spaßkommentaren verübeln. Wer gerne Spaßkommentare liest, kann z. B. auf StackOverFlow fündig werden, aber bitte nicht im Code.

Auskommentierter Code

Meist handelt es sich um unfertige Umsetzungen oder prototypische Implementierungen, welche auskommentiert sind. Da dieser Code durch das Auskommentieren nicht mehr mit refaktorisiert bzw. weiterentwickelt wird und zudem beim Bau der Software keine Rolle mehr spielt, veraltet er schnell und wird daher auch nicht mehr funktionieren, wenn er irgendwann wieder in das Leben zurückgerufen wird. Auskommentierte Codestellen sind lediglich “Erinnerungsstücke aus vorangegangenen Zeiten” neben dem Code, der aktiv in der Entwicklung ist. Es ist einfach nur verschwendete Zeit, wenn ein Entwickler auf auskommentierte Codezeilen stößt, da er ihn automatisch lesen wird – oder schlimmer – versucht ihn zu verstehen. Mit auskommentierten Code kann daher nur ein sinnvolles Vorgehen gelten: Löschen! Zur absoluten Not kann der gelöschte Code auch noch einmal eingesehen werden, da in jedem (normalen) Softwareentwicklungsunternehmen ein Versionskontrollsystem verwendet wird, um (bei entsprechender Wichtigkeit) die vorhandenen “Reminder” im Code wieder zum Leben zu erwecken.

Prinzipien für bessere Kommentare

Es gibt viele Variationen von Kommentaren, aber wie kann ein Entwickler nun konkret vermeiden, seine Zeit mit unnötigen Kommentare zu vergeuden? Es existieren ein paar Prinzipien, welche uns im täglichen Umgang mit Code und Kommentaren helfen, eine bessere Grundeinstellung zu bekommen:

You Aren’t Gonna Need It: Vor dem Kommentieren sollte noch einmal über den Sinn, Zweck und Mehrwert des geplanten Kommentars nachgedacht werden.

Don’t repeat yourself: Kommentare sollten nicht mehrfach vorkommen. Falls sie das tun, ist dies ein Zeichen, dass eine Vorgabe oder Konvention vorliegt, welche in ein separates, übergreifendes Dokument bzw. an eine entsprechend gemeinsame Stelle im Code gehört.

Single Point of Truth: Der Kommentar sollte immer dort angebracht sein, wo er auch benötigt wird oder wofür er wichtig ist.

Make things as simple as possible, but not simpler: Kommentare sollen schnell gelesen und verstanden werden können. Prosahafte Ausführungen bitte lieber als Quellcode mit passenden Sprachmitteln realisieren.

Mit diesen Prinzipien kann bereits ein Großteil von wiederkehrenden Fragen heuristisch beantworten werden.

Deine nächsten Schritte für bessere Kommentare

Mit folgenden Aktionen kannst Du Kommentare im Quellcode gleich verbessern:

• Bekämpfe sinnlose Dienstanweisungen, welche zu unsinnigen Kommentierungen führen!
• Stelle Dir vor dem Kommentieren die Frage: Kann ich das auch über den Quellcode ausdrücken?
• Korrigiere oder lösche falsche oder irreführende Kommentare!
• Lösche alle autogenerierte und auskommentierte Kommentare!
• Und natürlich: Leite diesen Blogbeitrag an deine Kollegen weiter, um ihnen zu zeigen, dass es durchaus noch sinnvoll ist, Kommentare im Quellcode zu verfassen 😉 !

Bildnachweis: Designed by Graphiqastock / Freepik