Inline comments within code are “evil” and everybody who still uses inline comments today is a really, really bad developer and should get his license revoked. That’s what seems to be consensus throughout the developer community … or at least throughout the “up to date” community.
Okay, but I say that we need more inline comments. So, what’s wrong with me? Have I gone completely nuts?
Now, while answering the last two questions might be a difficult task … 😉 … my idea about inline comments is quite straightforward:
If you want to understand any kind of solution, i.e. whenever you need to implement some new feature within an existing, yet unknown code base, you need at least three essential questions to be answered:
- Why?
- What?
- How?
So, how will you get these questions answered without having the original developer at hand?
- The “How” is simple. That is the code in itself. Thus, it definitely makes sense to write the code as understandable as possible that everybody else will understand the “How” as easy as possible.
- The “What” is usually the domain of the class/method/function/… header. The comment header describes “What” the piece of code down below is meant to do. In Java that is the domain of the Javadoc, other programming languages have their own means or conventions for that.
- But where is the “Why”? The code itself cannot answer the question for obvious reasons and the Javadoc, etc. is not meant for this. It has to focus on the “What”. You could put the “Why” part to a separate artifact, an extra document, i.e. a design document or whatever. But that is quite cumbersome. Also there is a high probability that any changes, refactorings, etc. in the code wouldn’t find their way into that document so that it becomes obsolete quite fast. Hence, it would be better to place the answers to the “Why” questions right at the place where you can see the effect of the corresponding decision, right next to the code that shows “How” the decision of the “Why” question was implemented.
That’s where inline comments come in handy. They provide a perfect means to describe rationale for certain decisions that you find within the code. Whenever you think “Why the heck did he or she implement that piece of code this way?” it would be just perfect to find an inline comment right next to the piece of code that answers that question, wouldn’t it? But today most of the time you will look in vain for those answers. Instead you might have to ask the original developer if he or she is still around and remembers that decision or that knowledge is gone for good and you have to guess the rationale.
Thus, for me the domain of inline comments is answering “Why” questions and from my experience from a maintainability and changeability perspective (that’s where the architect inside kicks in 😉 ) understanding the “Why” is often a lot more important than understanding the “What” … and the “How” is laid out in the source code anyway.
That’s the reason why I say that we need more inline comments
- not for explaining the “What”, that’s the domain of the header comments
- not for explaining the “How”, the code should answer that by itself
- but for answering those “Why” questions, to provide the rationale for design and implementation decisions that are missing most of the time
Therefore here’s my concluding tip for you:
Kick that rule off your coding standard that says
“You are not allowed to use inline comments”
and replace it with
“You should use inline comments only to explain (non-obvious) design and implementation decisions (“Why” questions) … and don’t forget to use them for this purpose!”
Was this post helpful?
More articles
fromUwe Friedrichsen
16.10.2018 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
More articles in this subject area
Discover exciting further topics and let the codecentric world inspire you.
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 author
Uwe Friedrichsen
CTO
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.