/* no comment */ – über Sinn und Unsinn von Kommentaren

Gerade musste ich zum gefühlt millionsten Mal in einem unserer Sanierungsprojekte einen Kommentar wie den Folgenden lesen (anonymisiert bzw. abstrahiert, Child und Parent heißen in Wirklichkeit anders):

// Adds Child to Parent.
private void addChildToParent(Child child)

“Ok, ist doch wohl richtig”, könnte man meinen und tatsächlich ist der Kommentar inhaltlich zunächst ja nicht falsch. Und Kommentare sind schließlich wichtig, oder nicht? Auch ich habe an der Uni noch gelernt, viel und ausführlich zu kommentieren. Was mich dann daran stört? Nun, eine ganze Menge:

1. Der Kommentar bietet keinen Mehrwert. Nichts, was er aussagt, steht nicht ohnehin schon im Code. Oder wie mein Kollege Johannes sagen würde, die Signal-to-noise ratio des Codes ist schlecht. Ich möchte ergänzen: Und ein Verstoß gegen DRY obendrein.
2. Um Punkt 1 herauszufinden, musste ich den Kommentar aber erstmal lesen. Vergeudete Lebens- und Projektzeit und damit Geld (des Kunden). Ganz abgesehen vom Schreiben desselbigen…
3. Redundanzen sind schwer zu warten. Wird die Methode zu private void AddChildrenToParent(Child[] children) geändert, muss auch der Kommentar angepasst werden. Geschieht dies nicht, beginnt der Kommentar zu lügen – und kein Unit Test oder CI-Server der Welt wird darauf hinweisen, dass der Kommentar fälschlicherweise nicht zusammen mit dem Code angepasst wurde. Was in diesem einfachen Beispiel noch verschmerzbar erscheint, hat in richtigen Projekten schon oft große (und vermeidbare!) Aufwände verursacht.

Auch Robert “Uncle Bob” Martin ist in seiner Formulierung zu solchen Fällen ziemlich deutlich: “Redundant comments are just places to collect lies and misinformation.”

Was sollte nicht kommentiert werden?

Alles, was ohnehin schon im Code steht oder als Code ausgedrückt werden könnte.

Mit anderen Worten: Kommentare wie der eingangs gezeigte gehören ersatzlos gelöscht. Kommentare, die durch eine Umformulierung des Codes zu Redundanzen gemacht werden können, gehören ersatzlos gelöscht, nachdem der Code entsprechend angepasst wurde.

Die Zeile int weight; // weight in kg zum Beispiel sollte besser geschrieben werden als int weightInKg; (oder gleich eigene Klassen für Gewicht und Kilogramm eingeführt werden). Einige Entwickler stören sich daran, dass auf diese Weise sehr lange Bezeichner entstehen können. Beinhalten resultierende Methodennamen dann auch noch Konjunktionen wie And, Or oder If, besteht drigender Verdacht auf einen Verstoß gegen das Single Responsibility Principle (bzw. gegen methods should do one thing). Dann ist ein Refactoring ohnehin geboten. In den anderen Fällen halte ich mich ganz an Uncle Bob, der sagt: A long descriptive name is better than a short enigmatic name. A long descriptive name is better than a long descriptive comment.

Auch Konstanten können helfen, Kommentare zu eliminieren: int perimeter = radius * 2 * 3.14; // Pi is 3.14 lässt sich ohne Kommentar schreiben als:

const int PI = 3.14; 
int perimeter = radius * 2 * PI;

Ähnliches gilt für Blöcke innerhalb von Methoden. Häufig werden Kommentare in solchen Fällen eingesetzt, um inhaltliche Zusammenhänge zu verdeutlichen:

private void initParent()
{
    // initialize primitive fields
    answer = 42;
    foo = "bar";

    // initialize child 1
    child1 = new Child();
    child1.parent = this;
    child1.setAnotherImportantAttribute = "I am initialized. Yeah!";
    child1.doSomeImportantInitializationStuff()

    // initialize child 2
    ...
}

Ohnehin besser, da übersichtlicher, wäre hier ein Extract Method-Refactoring und das Entfernen der Kommentare:

private void initParent()
{
    initPrimitiveFields();
    initChild1();
    initChild2();
}

Was sollte kommentiert werden?

Alles, was nicht als Code ausgedrückt werden kann. Das sind vor allem Hintergrundinformationen und Begründungen, warum etwas auf die vorliegende Art und Weise implementiert ist.

Zusätzlich können Kommentare an öffentlichen APIs sinnvoll sein, um Entwicklern während der Programmierung gegen diese APIs Informationen zu deren Nutzung direkt in der Entwicklungsumgebung anzuzeigen.

Wie sollte kommentiert werden?

Kurz und prägnant, und unter Nutzung derselben Begriffe, die auch im Code auftauchen (im Domain Driven Desgin würde man sagen in der Ubiquitous Language).

Fazit

Kommentiere so viel wie nötig und so wenig wie möglich.

Daraus folgt:

• Lösche unnötige Kommentare.
• Mache Kommentare unnötig durch aussagekräftige Bezeichner, Einführen von Konstanten, Refactorings und Umformulierungen von Code im Allgemeinen (und lösche sie dann).
• Vor dem Schreiben eines Kommentares halte kurz inne und überlege, ob er wirklich nötig ist (oder unnötig gemacht werden kann).
• Metriken, die das Verhältnis von Code- zu Kommentarzeilen analysieren, haben keine Aussagekraft, nutze sie nicht.
• Automatisch generierte Kommentare sind immer redundant, erzeuge sie nicht.

---

Über den Autor

Silas stieß 2015, nach 15 Jahren Produktentwicklung & Forschung, zu MaibornWolff. Schwerpunkte des Informatikers aus Leidenschaft bilden Software-Architekturen, agile Softwareentwicklung und System- & Architektur-Audits. Software- und Code-Qualität sind ihm ebenso ein Herzensanliegen wie Teamkultur und Collective Ownership. Er hat Abschlüssse in angewandter und Wirtschaftsinformatik. In der Freizeit gelten für ihn die wichtigen 4C: Code, Coffee, Cocktails — and Climbing.