Do code comments suck?
A conversation about comments.
--
What is a comment?
A comment is a line in your source code file that can be read by developers but is ignored by compilers and interpreters.
What’s the point of that?
Code is often hard to understand. Adding descriptive text allows developers to explain their code to those who will maintain the code afterwards.
Need proof? Take the uncommented code below:
This block of code does several things. The result is that it is difficult for programmers to easily understand what it does.
Now consider the same code with comments.
Doesn’t this seem so much easier to understand than before the comments were added? This is because a comments describe what the code is doing. whereas the code is describing how it is happening.
As developers we like to think in ‘what’s and not ‘how’s.
So comments help us clarify our code?
Yes.
That sounds like a good thing…
Yes it is. However there are many ways to clarify our ideas in code. Of these ideas, comments are the worst.
So what makes comments ‘the worst’?
Well there are a few things. The first is that there is no guarantee that someone will read them. In fact, most developers just don’t bother. Our tooling is even against us. Take a look at this Webstorm screen cap. The default colour scheme makes comments a light easy-to-ignore grey:
So why not just write a blog called ‘Please Read Comments’?
That’s a good question. It’s because you can’t trust the comments you read.
The executable code you write is a source of truth. We know it’s true because we are actually running it. Comments are an alternative source of truth but there is nothing to guarantee the truthfulness of them.
Just like any other system where there are multiple sources of truth it is common for a developer to update one source and forget to update another. Can you honestly say that when you change code you read through all the surrounding comments to ensure that they remain correct?
Well no, it’s an easy thing to forget.
Exactly. So always make sure your systems have one source of truth.
Ok I accept, comments aren’t perfect. Nothing in this world is. Are you saying you have a better plan?
Yes. You show me your comment, and I’ll show you a better alternative.
What about a comment that describes what a variable is, are you saying that it isn’t good to clarify what your variables are for?
Clarifying what variables do is super important. That’s why we give them names. If you give your variable a meaningful name then you have no need for a comment. Better still, every place that the well-named variable is used the maintainer of your code is reminded what it’s for. There’s no need to stop reading and refer back to it’s definition. Look how much nicer the second code is.
This applies to functions too doesn’t it?
Yes. Give functions and their parameters names that describe what they do. If you do that, there will be no need for a function header style comment.
So what about your code from earlier, those comments describe blocks of code that achieve functionality together. That can’t be helped by good naming, can it?
Yes it can. A few lines of code that do one thing together can be extracted into well named functions. Have a look:
See how the code to create an alien is now in a function that describes what it does? Same story with the stats code. The code above needs no further explanation, it does what it says.
Using a function here also has the advantage that details are hidden. The maintainer doesn’t have to worry about how the functions work if it’s not relevant to the particular change that they are making.This makes the code easier to understand.
The maintainer also can’t ignore the function name as they might ignore a comment. The function name is the code and thus to read the code they must read the function call and the function name.
So what about if I have to heavily optimise some code, can I use comments then?
Yes.
Wait, what?
We are Software Engineers. Engineers have tools. Comments are tools, so are functions, so are variable names. No tool fixes every problem. No tool is completely redundant. When the code can’t be improved through structuring it in a way that makes it understandable, comments are the best choice.
So comments are good?
No, comments suck! Most comments that I see in the wild are inappropriate. In particular comments are used as an excuse for:
- Bad naming of variables or functions.
- Excusing functions for being too long or too complex.
However the rule that comments suck is a rule of thumb not a absolute. There are rare uses for comments too.
You there! Listening in, What do you think? This conversation doesn’t identify every bad or good use of comments. Can you think of another example of bad commenting? What about another exception to the rule?
