Code commenting, while controversial, is still considered a good practice. Comments are most often used to improve code readability, make it easier to maintain and explain certain decisions. But do comments always help, or do they bring more harm than good?

Just to clarify: I am not telling you to never ever write comments and bring down everyone who does. As with any rule, there are exceptions. But I am going to argue that most of the time, commenting is not a wise decision. Also, this is my subjective opinion, and I would love to hear some objective criticism in the replies!

When comments do not work: readability

One of the most obvious reasons for commenting is to explain what a certain block of code does. Paradoxically, this is the least obvious reason to not use comments.

Firstly, if your code needs comments to make sense, you should take a step back and reevaluate it. Is there anything you can do to make it more readable? Is there anything you could refactor? The code itself is a language (a deterministic one, as well) so why do you need to bring in another language (an ambiguous one) for it to be understandable? Consider these examples: the first one is bad code with comments, the second one is refactored and without comments. Which one is easier to read?

This code is part of an (imaginary) recommendation system that gets you related pages based on tags. Examine the differences between these two: the first file had bad, but extensively documented code, the second one has clean and understandable code, but with no comments. Not only it has no comments, but I dare you to try to write one: there is simply nothing left to say that is not already said in the code itself. These examples also have a hint for my next argument. Can you spot it?

When comments do not work: source of truth

One of the main principles a good programmer holds dear is DRY: Do not Repeat Yourself. It highlights that your code should have a single source of truth. Using this bare guideline you will avoid may bugs and mistakes. But comments violate this principle directly.

Code never lies, comments sometimes do

Ron Jeffries, one of the founders of Extreme Programming methology

Did you find the issue I mentioned in the previous example? The comment for the function said that related pages should have 75% matching tags, but the code itself used 85%. Most likely, the spec changed, the programmer updated the code but forgot to update the comment. Now there is an ambiguity that will confuse everyone who is going to work with this code.

The second example has no such problem. The threshold is stored in a constant, whose name serves the same purpose the comment does: clarifies its purpose. When you find yourself writing a comment, ask yourself: do you state anything in the comment that is already stated in the code and can become outdated?

When comments work: API documentation

Enough of comment criticism, now I will talk about cases when commenting is completely appropriate and even desired. If you are designing an API or a library that is served to end-user (or even other programmers in your team), you will want to have documentation. Documentation also violates the single source of truth principle, but it is just something we have to deal with. But what we can do is move the documentation as close to the code as possible. There are a lot of solutions out there (JavaDoc for Java, react-docgen for JS/React, etc.) that will automate documentation generation based on comments. Examine this snippet from the material-ui library: these comments are used to generate the markdown documentation, which is later used to generate the documentation website:

You can push it even further and generate comments based on other comments! Here is another example from material-ui, where comments/types from TypeScript definitions are used to generate JavaScript comments:

When comments work: decision making

There are cases when the code readable and concise, but it is not clear why it is written in such a way (maybe unconventional and/or inefficient). There may be very good reasons for it, and, as an explanation and possibly a warning, you can leave a comment clarifying it. An excellent example of what I mean is this comment:

// 
// Dear maintainer:
// 
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
// 
// total_hours_wasted_here = 42
// 

Credits to @jensroland and his StackOverflow answer.

When comments work: tutorials

While this may be out of the scope of this article, tutorials are an excellent place for comments and the only type of code where this is appropriate:

const apples = 5; // set apples to 5

Just remember to delete them when you switch from tutorials to production!

Thank you for reading it to the end, I hope you liked this article and will be more considerate while leaving comments in your code. I will say that this article is inspired by books like Clean Code (not an ad/referral) which I strongly encourage you to read.