My take on writing (good) comments

A couple of days ago Jack Franklin, a well-known developer, writer, speaker and more recently podcaster, has written a blog post about writing code comments, explaining how good comments are “about the why, and not the how” and trying to debunk the notion that “code that needs comments is bad code”.

I invite you to read it, it’s clear, concise and well-argued (classic Jack!): https://www.jackfranklin.co.uk/blog/code-comments-why-not-how/

I 100% agree with him, apart from one point: I think we can push back even further against this idea that comments are useless, or “wrong”.

Let’s start from the code that he uses as an example:

// set the input value from the ENV value bar
const inputValue = process.ENV.bar

// now multiply it by 2
const newValue = inputValue * 2

// now pass it to the square function
const finalValue = square(newValue)

// this function squares a number and returns the new number
const square = (x) => x * x

This snippet of code doesn’t look like this in a modern IDE/Editor, but more like this:

Thanks to the code highlighting, I am sure we all have developed some sort of “comment blindness” when we read code (similar to the notorious banner blindness), that allows us to completely skip the comments and read only the lines of code. So this whole idea that “useless code comments add noise”, often used in this kind of debates, I think is weak, to say the least.

Now, let’s focus on the idea of usefulness of code comments. If something is useful or not, is a very subjective thing. If a code comment is not useful for you, doesn’t mean it is not useful for someone else. Who are you writing code comments for? What if the code comment will be useful for a junior developer that will be hired and will have to work on that piece of code, and make their understanding of the codebase easier? What if it will be useful for your colleague, when doing the code review, to understand your intent? What if it will be useful for the “future” you, when months later you will have to work again on that piece of code, and you will have completely forgotten what it does, how it works, etc.?

Even comments that are obvious like the “now multiply it by 2” may have their reasons. Take another look at the code above, and focus only on the comments, the grey lines. See how they tell a story?

set the input value from the ENV value bar
now multiply it by 2
now pass it to the "square" function
(this function squares a number and returns the new number)

If you want to have an overview of what a piece of code does, maybe a piece of code that someone else has written (or you did, but you don’t remember anymore, and it happens, trust me!), this is a very effective way of having some sort of index, for large blocks of code. You can read the comments, have a general idea of the flow, the logic, the steps, and then dig into the actual code with a mental map of what to expect. You can have two “narratives” in the same code: one that you can “read” as a plain human-readable text, and one that you can interpret in terms of actual code.

I’ve done it hundreds of times, to the point that now has become second nature for me. And trust me, it doesn’t add any overhead to your work. On the contrary: it gives you time to stop for a second and think what you have written in code (or are going to do, depending on the coding style) and see if makes sense, does what it’s supposed to do, and how it fits with the rest of the code. It’s a moment in which you can look at the code in a more rational and detached way. And I am pretty sure that whoever had to work on my code after me, never complained (at least with me 😁) about too many comments in it. In some cases, the comments written in this way abundantly helped me, when I had to work again on it, months later.

Does it mean that every line of code now needs to have its own comment? No, not at all. That’s not what I am saying. What I am saying is to stop being so dogmatic (and to be clear, I’m not referring to Jack here, but to the “comments in code are bad” school of thought) and scaring off people of writing comments. There’s nothing wrong with it.

So maybe the question is not about the how or the why, both valid reason for me to add a comment, but the where: where should we add comments?

If I look at where I tend to add comments, I see it’s where I feel I have to explain to someone else what I am doing. In particular:

• if I have struggled to come up with that particular piece of code, even if the code itself it’s simple (it may have required a lot of work/thought to produce it);
• if there’s something special in that code, that may be missed at first sight;
• if there is some knowledge that I want to transfer/share/remind with whoever will work on that code in the future;
• if a sequence of comments can give a simple overview of what the code does.

I know this is very subjective too, and that it can’t be converted to a “general rule”, but that’s the whole point: comments are written only for humans (code is written for humans and machines, but that’s another story) and everything about humans is subjective.

We need more empathy for our colleagues, for other developers, other people in the community, that may be at different stages in the process of learning to code, and may find useful a comment to a piece of code that for us may look trivial. In the end, it’s about making our code more “accessible”, no?

---

PS: I have used Jack’s article as a pretext for discussion, to try giving a different point of view, that I see is often neglected. I admire Jack and the work he’s done in all these years (he knows because I told him many times) so don’t look at this post as a criticism of his article but as a further point of view on the matter.

Link: https://www.jackfranklin.co.uk/blog/code-comments-why-not-how/