Do code comments suck?

A conversation about comments.

Sam Fare
Sam Fare
Aug 2, 2018 · 4 min read
“Close-up of a person's hands on the keyboard of a MacBook” by Glenn Carstens-Peters on Unsplash

What is a comment?

What’s the point of that?

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?

That sounds like a good thing…

So what makes comments ‘the worst’?

Some code with a hidden comment.

So why not just write a blog called ‘Please Read Comments’?

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.

Ok I accept, comments aren’t perfect. Nothing in this world is. Are you saying you have a better plan?

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?

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?

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?

Wait, what?

So comments are good?

  • 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?

Compare the Market

The people behind comparethemarket.com and the Meerkat App

Sam Fare

Written by

Sam Fare

Senior Software Engineer at booking.com. Also do tweeting: https://twitter.com/SamuelFare

Compare the Market

The people behind comparethemarket.com and the Meerkat App

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade