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!“
War dieser Beitrag hilfreich?
Weitere Beiträge
von Uwe Friedrichsen
16.10.2018 Dein Job bei codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
Weitere Artikel in diesem Themenbereich
Entdecke spannende weiterführende Themen und lass dich von der codecentric Welt inspirieren.
Gemeinsam bessere Projekte umsetzen.
Wir helfen deinem Unternehmen.
Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.
Hilf uns, noch besser zu werden.
Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.
Blog-Autor*in
Uwe Friedrichsen
CTO
Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.
Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.