Wir brauchen mehr Inline-Kommentare!

5 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!“

Autor

Uwe Friedrichsen

Share on FacebookGoogle+Share on LinkedInTweet about this on TwitterShare on RedditDigg thisShare on StumbleUpon

Kommentare

  • Tobias Trelle

    September 27, 2010 von Tobias Trelle

    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!

  • September 27, 2010 von Lothar Fischer

    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.

  • 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

  • November 19, 2010 von Emerson

    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.

  • 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 … 😉

Kommentieren

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