Overview

We need more inline comments!

2 Comments

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!”

Kommentare

  • Thomas Ferris Nicolaisen

    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.

  • Bastian Krol

    27. September 2010 von Bastian Krol

    +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”.

Comment

Your email address will not be published. Required fields are marked *