Blog
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/
Archive
-
Design Tokens beyond colors, typography, and spacing.
January 16, 2020 -
Memo: “Refactoring — Not on the backlog!”
An amazing article about how to approach refactoring in a codebase
November 21, 2019 -
Measuring the Impact of a Design System
January 29, 2019 -
New Year‘s (non) Resolution for 2019
Just a list of simple things that I want to do this year
January 9, 2019 -
Generating multi-brand multi-platform icons with Sketch and a Node.js script — Part #2
Second part: the build script and the generation of the assets.
December 6, 2018 -
Generating multi-brand multi-platform icons with Sketch and a Node.js script — Part #1
First part: from the idea to the assets Sketch files.
December 5, 2018 -
How to manage your Design Tokens with Style Dictionary
September 17, 2018 -
Keep it simple, stupid!
How one line of CSS code saved me hours of React development
April 6, 2018 -
Technical debt in a quip
March 21, 2018 -
Autobiography in Five Short Chapters
A quote from “There's a Hole in My Sidewalk” by Portia Nelson
March 8, 2018 -
From zero to Cosmos — Part #3
Third part: where I show where we are today, and where we think we will be in the future
February 22, 2018 -
From zero to Cosmos — Part #2
Second part: here come the dragons, and where the “grand plan” takes place
February 14, 2018 -
From zero to Cosmos — Part #1
First part: where everything started, and where I reaped the fruits of my labour
February 5, 2018 -
Missed opportunities
A non zero-sum game
January 30, 2018 -
New Year’s Resolution for 2018
Smile. Be optimistic. Be bold.
January 3, 2018 -
Chemistry over Culture
An interesting discussion about the meaning of these two words, and possible implications in their use.
December 2, 2017 -
Let There Be Peace on CSS
A talk on a war that is dividing the CSS community, made in the name of the “separation of concerns”, and a peace that is starting to see the light, thanks to bright minds and passionate developers
October 1, 2017 -
Systemantics
A review of a book that has a lot to say about systems: how they works, how they fail, but most of all how we should build them
June 11, 2017 -
The first rule to reduce technical debt
An extended version, beyond the limit of 140 characters, of an interesting discussion
March 10, 2017 -
Big Data, Intelligenza Artificiale, Conoscenza.
Alcune riflessioni sul tema big-data e giornalismo
February 9, 2017 -
Classes (and IDs) aren’t owned by CSS
January 21, 2017 -
New Year’s Resolution for 2017
Being rich with all I have gained on the way
January 3, 2017 -
Our recruiting process is flawed
My experiences being interviewed for a job. And someone else's views on the recruiting process.
November 6, 2016 -
Style Guides, Pattern Libraries, Design Systems and other amenities.
November 4, 2016 -
I like it blue
Two hundreds years have passed, but still technical choices are discussed on the tip of personal taste
October 3, 2016 -
“More than”
An inspiring evening about interactions, humans, agents, instability and hacks.
September 29, 2016 -
Algorithms, Machine Learning, Artificial Intelligence and us Designers
A transcript of the Interaction Design London meetup
June 30, 2016 -
Brexit, things are easy
June 24, 2016 -
To BEM or not to BEM
A series of interviews on BEM methodology
May 12, 2016 -
The impact of code in society
Writeup of a special event in London
April 26, 2016 -
Industry Conf 2016
An unexpected conference in Newcastle
April 21, 2016 -
Diversity in Tech, we are getting there
Some good news from a very personal point of observation
March 2, 2016 -
Hello Badoo
I've joined the company as Mobile Web Developer.
January 25, 2016 -
Goodbye Plentific
After 16 months of hard work, it's time for me to take new roads
January 18, 2016 -
Post Agile
Una riflessione in pausa pranzo, nata da una discussione fra amici
January 6, 2016