The importance of comments - Part 1

I wrote about the importance of documentation a few weeks ago. In this post I will discuss a related, also controversially discussed topic: Comments.

As the discussion is too long for a single post, I decided to split it up in three posts. This post discusses the widespread, often dogmatic “clean code” comment confusion and why it is not useful. Additionally, the post discusses how to best (not) document the “how”.

The second post will discuss why we should write comments to document the “what”. The third post I will discuss some typical counter-arguments regarding the “what”-documentation, some additional considerations, how to document the “why” and sum it all up.

But let us start with the “clean code” movement and the downsides of its often dogmatic approach.

The “Clean code” confusion

With comments we have a similar problem as with documentation: Done right, they add a lot of value for their readers, but nobody wants to write them in the first place. This observation was true since the dawn of IT.

And then a book called “Clean code” was released. Regarding comments, the book basically states any comment is a “code smell”, a sign that you are doing it wrong, that your code is not “clean”.

The book was released in 2008: The Agile movement started to enter mainstream, Agile misunderstandings like the documentation confusion discussed before spread like mushrooms in a dark, moist environment. And still nobody wanted to write and maintain comments.

This setting was fertile ground for the statements about comments from the book. “Clean code” found a lot of followers – not only, but also for the book’s position regarding comments. A widespread reasoning across those developers became: “Clean coders do not write comments. Never!”

Let me be clear about “Clean code”: The book has some really good advice how to write better code. I personally do not agree with all ideas of the book (as this post should make obvious). But it definitely has quite some advice that can help you to write better code.

Having clarified that, let me come to the big downside of the book: The book is written in a very dogmatic way. It has many quite extreme positions that are combined with a strict black & white reasoning: Either you do it this way or you do it wrong! From all I have seen, this dogmatic approach has caused a lot of harm.

I can only guess why Robert Martin (the author of the book) took that dogmatic black & white approach that you see in many parts of his book. I assume that he was confronted with a lot with environments where a lot of things went wrong, where, e.g., people tried to disguise shoddy designs and implementations with a surplus of comments, where pointless comment guidelines were enforced, and alike.

If you are a responsible developer and come to such an environment, your normal reaction is to point out the problem, to push writing better code in the first place instead of disguising your coding shortcomings behind tons of useless comments. Such a reaction is sensible.

Robert Martin did not chose this way in his book. He went to the extreme counterposition: He took the position that writing comments is a failure per se.

This is the evangelist’s approach: You want to change something. You take the extreme counterposition and expect that after the inevitable discussions and fights eventually you end up in the place where you actually want to be. This approach takes into account that

• you need a clearly differing position if you want to change a status quo. The more solidified the status quo is, the farther away, the more provoking a differing position must feel to trigger a change discussion.
• in a sane environment you will agree on a compromise in the end. This means the further the status quo is away from the position you consider good, the farther away your initial position must be from the status quo, i.e., the more extreme your initial counterposition must be.

This is a valid approach if you find yourself confronted with a situation that you consider bad and want to trigger a change in the right direction (leaving aside that “good”, “bad”, “right” and “wrong” are in the eye of the beholder). ¹

Unfortunately, the statements from the book were not used so much to drive a discussion to find a sane middle ground but often turned into a dogma. Sensible discussions became impossible: Comments are bad! If you are not 100% with us, you are against us! If you even have a slightly deviating opinion, you are an enemy!

That was the type of non-discussion, you often were confronted with in the first years of the “clean code” movement. Meanwhile, the overall emotions have cooled down a bit, but sensible discussions about comments often are still not easy.

If the whole no-comments movement would have been focused on creating more value, it would have been strenuous, but okay. Fighting for more value is a good reason for not giving in so easily. Unfortunately, most discussions felt a lot more like a mixture of unreflected dogma that nicely supported personal convenience.

Most of the time, it felt a lot like: I do not like to write comments. I also lack the discipline to keep them up to date. Hey, look! Uncle Bob says that writing comments is bad. So, I am a clean coder! My personal issues with comments are not a flaw. They are the proof that I am a great coder!

While the motivation of all people involved is perfectly understandable, unfortunately a lot of value was destroyed with the no-comments dogma. While comments at the wrong places for the wrong reasons are waste and signs of unresolved deficiencies in other places, no comments at all almost always destroy value.

A sensible comment hygiene

Like documentation, comments are meant to support the readers, not the writers. Yet, as code is read orders of magnitude more often than it is written, supporting the readers in the right places with a good comment can save lots of time overall and avoid lots of misunderstandings and accidental errors.

This raises the question: Where and when are comments useful (and when should I avoid them)?

I tend to differentiate the “why”, the “what” and the “how”:

• The “why” describes the motivation behind a specific implementation, why you did it the way you did it.
• The “what” describes what the code is doing, being sort of a specification or contract.
• The “how” is the implementation itself.

If I take this differentiation, it leads me to the following rules of thumb:

(Not) documenting the “How”

My personal rule of thumb is:

Do not comment the “how”. The code should be the documentation of the “how”.

There is not any value in starting a for-loop with a comment that an iteration starts. It is obvious. No comment needed for explaining that.

If your code is so incomprehensible that nobody understands it without comments, do not add comments. Instead, work hard to turn your code into comprehensible code. That is BTW where the “Clean code” book offers a lot of good advice: How to create code that is easy to read.

There might be some rare exception when it is inevitable to write some code that is very hard to understand. E.g., you write code for an embedded device. For performance reasons you need to implement some tricky bit shifting and masking. In such a situation, commenting the “how” a bit can make sense. But that should be the rare exception.

Sometimes I heard the argument that commenting the “how” is needed to make the code approachable for persons who do not understand code. My take on that argument is simple: Either learn to read code or stop trying to read code. It is not that hard to learn a programming language good enough to be able to read code (writing code is a different story, though).

If you are not willing to learn reading code, accept that you then need to discuss the “how” by different means. But do not force developers into useless commenting misery just because you are not willing to spend a bit of time learning how to read code. Code is for people who know how to read code. If you want to discuss it, learn to read it. Again, it is not that hard.

Summing up

In this post we discussed why the widespread “clean code” approach not to write any comments destroys value in its dogmatic interpretation. We also discussed that we should not document the “how” as the code already does it.

In the next post we will discuss why we should comment the “what”. Stay tuned … ;)