Wir brauchen mehr Inline-Kommentare!

Inline-Kommentare im Code sind “böse” und jeder, der heutzutage noch immer Inline-Kommentare verwendet, ist ein sehr, sehr schlechter Entwickler und man sollte ihm dringend seine Lizenz entziehen. Das ist es, was allgemeiner Konsens in der Entwicklergemeinde zu sein scheint … oder zumindest innerhalb des Teils der Entwicklergemeinde, der sich “Up to Date” wähnt.

Schön, aber ich behaupte, dass wir mehr Inline-Kommentare benötigen. Ja, was ist denn los mit mir? Habe ich jetzt endgültig den Verstand verloren?

Nun, während die Beantwortung der letzten Frage eine durchaus diffizile Aufgabe sein könnte … ;-) … meine Gedanken bzgl. der Inline-Kommentare sind relativ einfach:

Wenn Du irgendeine Art von Lösung verstehen willst, etwa wenn Du ein neues Feature in einer bestehenden, Dir bislang aber noch unbekannten Code-Basis implementierten sollst, dann musst Du mindestens die Antworten zu den folgenden drei essentiellen Fragen kennen:

  • Was?
  • Wie?
  • Warum

Wie bekommt man diese drei Fragen beantwortet, wenn der ursprüngliche Entwickler nicht mehr verfügbar ist?

  • Das “Wie” ist einfach. Das ist der Code an sich. Aus diesem Grund macht es auch definitiv Sinn, Code so verständlich wie möglich zu schreiben, damit jeder andere das “Wie” so einfach wie möglich verstehen kann.
  • Das “Was” ist normalerweise die Domäne der Klassen-/Methoden-/Funktions-/… Header. Der Kommentar-Header beschreibt, “Was” das folgende Stück Software tun soll. In Java ist das die Domäne von Javadoc, andere Programmiersprachen haben ihre eigenen Mittel oder Konventionen dafür.
  • Aber wo bleibt das “Warum”? Der Code an sich kann diese Frage aus naheliegenden Gründen nicht beantworten und Javadoc, etc. sind auch nicht dafür gedacht. Diese sollten sich auf das “Was” fokussieren. Man könnte das “Warum” jetzt in ein separates Artefakt packen, ein Extradokument wie etwa ein Design-Dokument. Das ist aber recht umständlich. Außerdem ist die Wahrscheinlichkeit sehr hoch, dass irgendwelche Änderungen, Refactorings, etc. im Code nicht ihren Weg in das Dokument finden würden, so dass es sehr schnell veralten würde. Deshalb ist es eine wesentlich bessere Idee, die Antworten zu den “Warum”-Fragen genau an die Stelle zu setzen, an der Du den Effekt der zugehörigen Entscheidung unmittelbar sehen kannst, nämlich direkt neben den Code, der einem zeigt, “Wie” die Entscheidung der “Warum”-Frage implementiert worden ist.

Dafür kommen einem Inline-Kommentare gerade zupass. sie bieten ein perfektes Mittel, um die Begründung für bestimmte Entscheidungen zu liefern, die man im Code findet. Wann immer Du denkst “Warum um Himmels Willen hat er oder sie dieses Stück Code auf diese Weise implementiert?”, wäre es doch wunderbar, einen Inline-Kommentar direkt neben dem Stück Code zu finden, der einem diese Frage beantwortet, oder? Heutzutage sucht man aber leider meist vergeblich nach diesen Antworten. Stattdessen muss man versuchen, den ursprünglichen Entwickler zu fragen, sollte er noch greifbar sein und sich auch noch an diese Entscheidung erinnern oder das Wissen ist verloren und man muss den Grund erraten.

Aus diesen Gründen ist die Domäne von Inline-Kommentaren für mich die Beantwortung von “Warum”-Fragen und aus meiner Erfahrung ist das Verstehen des “Warum” aus einer Wartbarkeits- und Änderbarkeitsperspektive (hier kommt der Architekt in mir wieder durch … ;-) ) wesentlich wichtiger als das Verstehen des “Was” … und das “Wie” steht sowieso im Source Code.

Darum sage ich, dass wir mehr Inline-Kommentare benötigen

  • nicht, um das “Was” zu erklären, das ist die Domäne der Header-Kommentare
  • nicht, um das “Wie” zu erklären, das sollte der Code an sich beantworten
  • sondern um diese “Warum”-Fragen zu beantworten, um die Begründungen für Design- und Implementierungsentscheidungen zu liefern, die man meistens vergeblich sucht.

Und deshalb ist meine abschließende Empfehlung:

Schmeißt die Regel

“Du darfst keine Inline-Kommentare verwenden”

aus Euren Coding Standards und ersetzt sie durch

“Du sollst Inline-Kommentare ausschließlich verwenden, (nicht-offensichtliche) Design- und Implementierungsentscheidungen zu erklären (“Warum”-Fragen) … und vergiss nicht, sie dafür auch zu verwenden!”

  • Facebook
  • Delicious
  • Digg
  • StumbleUpon
  • Reddit
  • Blogger
  • LinkedIn
Uwe Friedrichsen

7 Antworten auf Wir brauchen mehr Inline-Kommentare!

  1. Tobias Trelle sagt:

    An die Regel

    “Du darfst keine Inline-Kommentare verwenden”

    habe ich mich nie gehalten. Allein formal lässt sich eben nicht alles mit JavaDocs (oder äquivalenten Kommentarformen in anderen Sprachen) ausdrücken, sofern man nicht eine Unmenge an Methoden schreibt.

    Also: volle Zustimmung!

  2. I agree on the point of having a strict policy on no inline comments is silly, as with most other strict coding policies.

    Of course, you should strive to avoid non-obvious code in the first place. Inline comments shouldn’t be an excuse for getting away with writing crap code.

    I might be referencing the Clean Code book here: A method should contain instructions that work on the same level of abstraction. If you’re mixing non-obvious code with obvious code in the same method, chances are that the method is trying to do too many different things.

    Whenever I feel the itch to write an inline comment, I consider that the next few lines could probably be extracted into a private method. I then describe the reasoning in the JavaDoc of this extracted method. If I just want to comment on a one-liner, it’s fine to do so inline.

  3. Bastian Krol sagt:

    +1 with some tiny “buts”

    I like the separation into What, How, Why – it’s very catchy. However, my very personal “golden rule” about inline comments goes slightly different:

    First, by all means write your code in a way that is so simple and obvious that it does not need to be commented. While writing a comment for a non-obvious design decision, ask yourself: Could I do that with a simpler design which is more obvious? (Of course, you could/should have asked that before, but sometimes for me it’s only when I try to explain the solution that I recognize that it is, well, sub optimal…)

    Second, only if that fails, use comments. But then, by all means, use them and write clear and comprehensible.

    But perhaps this is just another wording for the same thoughts.

    Another aspect regarding comments that comes to my mind. If you follow the Uncle Bob’s advises from the book Clean Code, you end up writing a lot of very small methods. In this approach, the method name often plays takes the role of a comment in lengthier methods. This helps a lot with writing self-explanatory code.

    Just my 2 cents…

    ====

    Die Aufteilung in Was, Wie und Warum gefällt mir gut ist schön plakativ und einprägsam. Allerdings lautet die (ganz persönliche) goldene Regel, die sich in meinem Kopf zum Thema Inline-Kommentare eingenistet hat, leicht anders:

    Priorität 1: Den Code wann immer möglich so schreiben, dass das “Warum” offensichtlich ist und keiner weiteren Kommentierung bedarf. (Spätestens) wenn man dabei ist, eine nicht-offensichtliche Design-Entscheidung zu kommentieren, sollte man sich fragen, ob es nicht doch auch einfacher geht.
    (Hätte man sich natürlich schon früher fragen können/sollen, aber ich persönlich merke manchmal erst in dem Moment, in dem ich versuche, die Lösung zu erklären, dass sie nicht das Gelbe vom Ei ist.)

    Priorität 2: Nur wenn das nicht geht, sollte man auf Kommentare zurückgreifen – die dann natürlich möglichst klar und verständlich formuliert sein sollten.

    Ist aber vielleich auch nur ein anderes Wording…

    Noch ein Aspekt, der mir dazu einfällt: Wenn man sich an den Vorschlägen aus Uncle Bobs “Clean Code” hält und viele sehr kleine Methoden schreibt, die recht wenig tun, übernimmt der Methodenname oft die Funktion dessen, was man bei längeren Methoden möglicherweise als Kommentar dazuschreiben würde. Das bringt das ganze schon mal ein gutes Stück in Richtung “selbsterklärend”.

  4. Lothar Fischer sagt:

    Bislang habe ich von einer Regel “Du darfst keine Inline-Kommentare verwenden” noch nichts gehört, was vielleicht daran liegt, dass ich offensichtlich kein Mitglied dieser wahnsinnig up-to-daten Entwicklergemeinde bin (vielleicht klärt mich ja noch jemand auf, wer das eigentlich ist.).

    Irgendwie bekräftigt es zwar mein Vorurteil, dass dort zu viele (Hobby-)Ingenieure und zu wenig erfahrene Handwerker zu Gange sind und daher zuviel akademisiert wird und zu wenig praktische Erfahrung einfliesst. Aber bei genauerer Betrachtung diverser populärer Design- und Implementierungs-Prinzipien (cleancode, dry etc.) ist fehlende Inline Doku doch nur konsequent. Die Erstellung des Quellcodes sollte ja eigentlich objektiv nachvollziehbaren Mustern folgen, das warum ist dann also inhärent vorhanden.

    Dennoch kann ich konsequente (Inline-)Dokumentation nur anraten, denn

    -Man hat auch mal einen schlechten Tag und wählt nicht den einfachsten Weg einer Implemetierung.

    -Man hat auch mal einen guten Tag und möchte den Jungs zeigen was man drauf hat.

    -Unterschiedliche Kenntnis der Problemdomäne lassen ein und denselben Code anders erscheinen.

    -Als Entwickler berücksichtigt man Dinge, die sich in keiner Spezifikation wiederfinden, weil man auch eigene Erfahrungen miteinbringt.

    -*Moderne* Sprachkonstrukte haben mittlerweile eine Komplexität, die sich nicht unbedingt auf den 1. Blick erschliesst.

    -Wenn der Code schon ein wenig lebt, leidet (allen guten Vorsätzen zum trotz) die Qualität, oftmals ja sogar während der primären Entwicklungsphase.

    Also, solange wir nicht in einer vollkommen formalisierten Welt leben, ist es gar nicht verkehrt wenn der Autor aufschreibt, was er sagen will.

  5. Hi,

    thanks for the great comments up to now. I totally agree with your remarks about clean code, etc. Often it is possible to avoid inline comments using a different design and sometimes it makes sense to use inline comments for other reasons.

    Yet my point was slightly different when talking about the “Why”. For an example: Some years ago I had to implement some _very_ strange stuff due to a bug in the DBMS we used. Without any comment the next developer would definitely thought that I had a _really_ bad day when coding that stuff because he wouldn’t have known “why” I did that. Especially he or she wouldn’t have known if that piece of code could be altered or not. Thus, even with the best design (that you should definitively should strive for) the “Why” is not always obvious without explaining it explicitly.

    So, the problem is often not understanding what the code does. The problem is to know if you can change that code without breaking the system. That’s why you see so often workarounds around non-understood code in existing systems, even if they were designed very well in the beginning.

    Ah, and testing does only solve that issue partially … ;-)

    Regards, Uwe

    ———————————————————–

    Hallo,

    vielen Dank für die bisherigen sehr guten Kommentare. Ich stimme voll mit Euren Anmerkungen bzgl. Clean Code, usw. überein. Oftmals ist es möglich, Inline-Kommentare zu vermeiden, indem man ein anderes Design verwendet. Und manchmal macht es aus anderen Gründen absolut Sinn, Inline-Kommentare zu verwenden.

    Dennoch hatte ich etwas leicht anderes im Kopf, als ich über das “Warum” geschrieben habe. Ein Beispiel: Vor einigen Jahren musste ich eine _ziemlich_ schräge Sache implementieren, weil unser DBMS einen Fehler hatte. Ohne einen Kommentar hätte der nächste Entwickler sicher gedacht, dass ich einen _echt_ schlechten Tag gehabt hatte, als ich das geschrieben habe. Insbesondere hätte er oder sie nicht gewusst, ob dieser Code geändert werden kann oder nicht. Deshalb ist auch mit dem besten Design (etwas, das man auf jeden Fall anstreben sollte) das “Warum” nicht immer klar, wenn man es nicht explizit erklärt.

    Das Problem ist häufig nicht zu verstehen, was der Code tut. Das Problem ist vielmehr zu wissen ob man den Code ändern kann, ohne das System kaputt zu machen. Deshalb sieht man so häufig Workarounds um nicht verstandenen Code in existierenden Systemen, selbst wenn sie initial richtig gut designed worden sind.

    Ah, und Testen löst dieses Problem auch nur teilweise … ;-)

    Gruß, Uwe

  6. Emerson sagt:

    Das Problem ist vielmehr zu wissen ob man den Code ändern kann, ohne das System kaputt zu machen

    So ganz kann ich diesen Kommentar nicht nachvollziehen. Soll das heißen, dass Kommentare eher dazu dienen die Sicherheit zu haben, dass man bei Änderung ein bestehendes System nicht kaputt macht ?

    Kommentare sind die ersten die veraltet sind und es auch bleiben. Code wird geändert, Kommentare aber (leider) selten nachgezogen. Hierfür sind Tests ein wesentlich besserer und sicherer Mechanismus. Wenn Tests nicht ein Systemfehler aufdecken sind die Tests fehlerhaft.

    Womöglich habe ich etwas falsch verstanden, doch sich auf Kommentare zu verlassen um die Integrität eines Systems zu sichern halte ich für gefährlich.

  7. Hallo Emerson,

    vielleicht zur Klarstellung: Es ging mir nie darum zu sagen, dass Kommentare besser oder schlechter als Tests geeignet sind, die Integrität des Systems sicherzustellen. Insbesondere bin ich auch ein klarer Befürworter von (automatisierten) Tests. Daher ja, Kommentare zur Sicherstellung der Systemintegrität halte ich ebenfalls für gefährlich.

    Ich habe nur ein Problem mit Schwarz/Weiß-Dogmen. Entweder ist irgendetwas gaaanz toll oder gaaanz schlimm. In diesem Fall waren es die Inline-Kommentare, die Opfer der Verteufelung bestimmter “hipper” Gruppen geworden sind. “Wer Inline-Kommentare braucht, kann nicht vernünftig programmieren”, so die mehr oder weniger explizite Aussage an diversen Ecken.

    Einer solchen Pauschalaussage muss ich einfach widersprechen, weil ich der Überzeugung bin, dass Inline-Kommentare ein hervorragendes Mittel sind, um die Idee hinter einer bestimmten Implementierung zu vermitteln, eben um “Warum”-Fragen zu beantworten.

    An der Stelle nützen Tests leider auch nichts. Ein Test beantwortet mir nicht, warum jemand seinen Code an einer Stelle genau in der vorliegenden Form umgesetzt hat, er beantwortet mir nur, was das gewünschte Verhalten ist. Das hilft mir aber im Zweifelsfall auch nicht weiter, wenn ich wissen möchte, warum etwas in der vorliegenden Form programmiert worden ist und ob ich das (ggf. inklusive zugehörigem Test) ändern kann.

    So gesehen: Ja, Test sind ein wichtiges Mittel, um die korrekte Funktionsweise einer Anwendung zu überprüfen, aber sie helfen einem nicht bei Warum-Fragen.

    Gruß, Uwe

    PS: Nebenbei gibt bei aller unbestrittenen Nützlichkeit von Tests trotzdem noch ein paar weitere Einschränkungen und Probleme, die gerne mal unter den Teppich gekehrt werden, auch in Bezug auf die problemlose Änderbarkeit und Überprüfbarkeit der Systemintegrität, aber das ist vielleicht mal ein Thema für einen anderen Post … ;-)

Hinterlasse eine Antwort

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind markiert *

Du kannst folgende HTML-Tags benutzen: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>