Kommentare im Code

- 4 Minuten - 667 Wörter

Aufgrund einer kleinen Diskussion zum Thema “Kommentare im Code” bei einem Code Review, habe ich mir (wieder mal) einige Gedanken dazu gemacht und möchte diese nun hier festhalten.

Konkret ging es um die Aussage:

Kommentare: So viel wie nötig, aber so wenig wie möglich.

Auch wenn ich den Hintergrund der Aussage verstehe und grundsätzlich unterstütze, halte ich sie für gefährlich weil sie sehr schwammig ist. Folgende Fragen tun sich dabei beispielsweise auf:

  • Wie viel ist denn eigentlich “nötig”?
  • Und wie wenig ist “möglich”?

Hier hat zweifelsohne jeder eine eigene, andere Meinung und wenn keine weitere Erklärung dafür geliefert wird, wird jeder Entwickler die Regelung anders handhaben - sowohl bei der eigenen Entwicklung, als auch bei einem Code Review. Ich hatte beispielsweise bereits einen Kollegen im Team der vor dem Einchecken seiner Quellen grundsätzlich alle Kommentare aus dem Code entfernt hat. Seiner Ansicht nach war das wohl so wenig wie möglich ;-)

Auch wenn ich ein Freund von “Guter, lesbarer Code ist bereits ein Teil der Dokumentation” bin, bin ich ebenso der Meinung: Es gibt nicht zu viele Kommentare im Code, aber es gibt falsche Kommentare im Code.

Falsche Kommentare

Alte Kommentare

Falsche Kommentare treten häufig auf wenn der Code aufgrund einer Anforderung geändert wird, aber der Kommentar nicht angepasst wird. Diese Art Kommentar ist sehr gefährlich und kann einen in die Irre führen. Hier muss jedem klar sein: Kommentare veralten. Bei Codeänderungen müssen die Kommentare also unbedingt mit aktualisiert werden. Das erfordert Disziplin aber fällt bei einem Code Review auch schnell auf. Eine große Hilfe ist es hier, wenn man ein gemeinsames Verständnis des Code Reviews hat.

Unnötige Kommentare

Eine kommentierte Schleife ist genauso unnötig wie eine Dokumentation einer selbsterklärenden Getter-Methode. Ich habe einmal mit einem Entwickler zusammengearbeitet, der eine Methode getCustomer() mit “Get the customer” kommentiert hat. Ich denke hier sind wir uns einig wenn wir sagen dass dieser Kommentar unnötig ist. Auch dies sollte jedoch spätestens beim Code Review entdeckt und angemerkt werden. Ich habe neulich zum Beispiel selbst erst einen unnötigen Kommentar im Code hinterlassen und beim Einchecken übersehen (nobody is perfect ;-)) - zum Glück hat mich ein Kollege beim Review darauf hingewiesen. Das ist gleichzeitig ein gutes Argument warum man Code Reviews in seinem Team einführen sollte. Aber das ist ein Thema das einen eigenen Beitrag füllen kann.

Gute Kommentare

Einem Gedankengang folgen

Kommentare geben Aufschluss darüber, was sich ein Entwickler bei seiner Lösung gedacht hat. Jeder sieht fremden Code, bei dem man denkt man könnte es besser lösen. Meistens hat sich der Autor aber etwas dabei gedacht. Vielleicht hatte er ursprünglich sogar die selbe “bessere” Idee die ich auch gerade habe. Aber beim Durchdenken oder Ausprobieren kam heraus dass das Problem auf diese Art nicht lösbar ist. Ein kurzes, aussagekräftiges Kommentar was ich mir dabei gedacht habe wirkt an dieser Stelle Wunder und verhindert dass ein nachfolgender Kollege in die gleiche Falle tappt. In meinen Augen kann ein solcher Kommentar niemals “unnötig” sein.

Den SOLL Zustand angeben

Oft höre ich dass der Code an sich genug Kommentar ist, aber der Code zeigt nur an was IST. Ein Kommentar gibt jedoch Aufschluss darüber was sein SOLL. Dies ist ein großer Unterschied und beides ist wichtig, gerade wenn wenig oder kein Anforderungsmangement vorhanden ist.

Übersicht bleibt dennoch erhalten

Mir wurde bereits gesagt dass Dateien mit wenig Kommentaren schneller durchgescrollt werden können. Da halte ich dagegen: In den Zeiten eines Mausrads und “Page up/down”-Tasten halte ich dieses Argument für irrelevant. Zusätzlich werden Kommentarzeilen von jeder aktuellen IDE entsprechend eingefärbt und das Gehirn blendet sie nach einer Eingewöhnungsphase automatisch aus. Sie stören damit nicht, weil sie bei einer Analyse des Codes automatisch “übersehen” werden. Ohne es explizit geprüft zu haben gehe ich auch davon aus dass es für die meisten IDE ein Plugin gibt, das auf Wunsch alle Kommentare tatsächlich ausblendet.

Resultat

Ich denke dass es besser ist wenn genauer definiert wird, welche Art Kommentare man in seiner Codebase wünscht und welche man bleiben weglassen soll. Leider ist es mit einem Satz jedoch nicht getan.