Kein Kommentar

Christian Siewert, 26. May 2016

A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments. – @KevlinHenney

Punkt. Oder andersherum: Wer verständlichen Code schreibt, braucht keine Kommentare. Denn: Wo Kommentare beschreiben, was der Code macht, sind sie meistens ein Hinweis auf schlechte Bezeichner, oder überflüssig, wenn er bereits offenbart, was er macht.

Kommentare kommen an unterschiedlichsten Stellen im Code vor und stören häufig den Lesefluss. Im Folgenden stelle ich einige vor und erkläre, wie ich sie eliminiere und wo ich sie zulasse.

Schlechte Bezeichner

Wie schon anfangs erwähnt, resultieren viele Kommentare aus schlechter Benamung:

//Der Code zum freischalten der Dll
CODE = 123456;

Das Beispiel sieht ersmtal nicht weiter schlimm aus. Doch liest man den Code, der CODE verwendet, dann kommen Fragen auf:

handle = library.load(CODE);

Hier wird nicht deutlich, welche Bedeutung CODE hat. Für die Information muss ich erst die Definition aufsuchen und den Kommentar lesen.

Wenn ich direkt einen treffenden Bezeichner wähle, kann ich auf den Kommentar verzichten. Alternativ kann ich einen vorhandenen Kommentar in Code umsetzen:

DLL_UNLOCK_KEY = 123456;

...

handle = library.load(DLL_UNLOCK_KEY);

Sprechender(er) Name, kein Kommentar! Der ist überflüssig geworden, weil die Konstante bereits aussagt, was 123456 ist. Beim Lesen der Logik werde ich nicht mehr unterbrochen, sondern weiß sofort: “Hier wird eine Dll geladen und ein Key übergeben, um die Dll freizuschalten!”.

Bedingungen

Auch Bedingungen sind häufig von Kommentaren umgeben. Ein Beispiel könnte sein:

// Handelt es sich um einen Werktag? 
if( (date.dayOfTheWeek >= 0) and (date.dayOfTheWeek <= 4) ) 
{
  // ...
}

Hier soll der Kommentar erklären, was die Bedingung überprüft. Das ist auf den ersten Blick hilfreich. Denn wir wissen jetzt, dass hier abgefragt wird, ob es sich bei date.dayOfTheWeek um einen Werktag handelt.

Den Lesefluss stört es dennoch, denn die genaue Definition eines Werktags ist für das Verständnis nicht von Interesse. Besser wäre z.B., die Bedingung in eine Funktion zu kapseln:

if( date.isWorkingday() ) 
{
  // ...
}

Jetzt sagt die Bedingung direkt aus, dass auf einen Werktag geprüft wird. Die Geschäftslogik lässt sich flüssig erfassen. Wenn mich trotzdem interessiert, was einen Werktag ausmacht, dann schlage ich die Definition von isWorkingday() nach.

Falsche Kommentare

Jetzt kann man anmerken, dass man sich glücklich schätzen sollte, wenn wenigstens ein Kommentar Licht ins Dunkel bringt. Leider kann man sich darauf nicht zu 100% verlassen. Die Korrektheit von Kommentaren ist nicht garantiert!

Es kommt nicht selten vor, dass Code geändert und dabei vergessen wird, die zugehörigen Kommentare zu aktualisieren. Oder schlimmer: Codezeilen wurden kopiert und leicht verändert, die Kommentare aber nicht angepasst. Sie lügen dann, wie @unclebobmartin es formuliert.

Kommentare, die falsche Aussagen über den zugrunde liegenden Code treffen, stiften noch mehr Verwirrung als schlechte Bezeichner. Gibt es Probleme mit dem betreffenden Code, muss man erforschen, ob das Programm korrekt ist und lediglich der Kommentar falsch oder umgekehrt.

An dieser Stelle kann man natürlich an die Disziplin des Entwicklers appelieren, Kommentare mit derselben Gewissenhaftigkeit zu pflegen, wie den Code. Ich bin der Meinung, dass man sich die Mühe sparen kann, indem man Kommentare einfach weglässt.

Redundante Kommentare

Generell kann man sagen: Wer Kommentare schreibt, wiederholt sich und verstößt damit gegen Don’t Repeat Yourself (DRY).

// Dll laden
handle = library.load();

// Constructor
SomeClass::SomeClass()

Hier beschreibt der Kommentar lediglich das, was der Code bereits ganz gut ausdrückt. Der Kommentar ist nur Geschwafel und deshalb überflüssig. Schließlich will ich nicht alles doppelt lesen.

Ausnahmen

Natürlich gibt es immer Fälle, in denen es sinnvoll (oder gar erforderlich) ist, Kommentare zu schreiben:

  • Um das Warum zu erklären, wenn es der Code nicht kommunizieren kann. Sinnvoll kann es z.B. sein, Quellen, Formeln, etc. anzugeben.
  • Um kritischen Code hervorzuheben
  • Um APIs zu dokumentieren. Wer APIs bereitstellt, sollte seinen Nutzern eine Dokumentation mitliefern, die er idealerweise direkt im Code bereitstellt. Mit DoxyGen bspw. lässt sich direkt aus Kommentaren eine Dokumentation generieren. (Hier wäre es sogar kontraproduktiv, bei Code-Änderung zusätzlich ein weiters Dokument anpassen zu müssen. Remember: DRY).

Fazit

Das Erstellen (und Lesen) von Kommentaren kostet Zeit, die man besser in das Schreiben lesbaren Codes steckt. Also sollte man sie generell vermeiden und auschließlich dort verwenden, wo der Code selbst nicht aufklären kann.

Oder, wie es Robert Pike (1989) auf den Punkt bringt:

First, if the code is clear, and uses good type names and variable names, it should explain itself. Second, comments aren’t checked by the compiler, so there is no guarantee they’re right, especially after the code is modified. A misleading comment can be very confusing. Third, the issue of typography: comments clutter code.
But I do comment sometimes. Almost exclusively, I use them […] as an introduction to an unusual or critical procedure; or to mark off sections of a large computation.

Ressourcen