Why You Should Limit Your Use of Comments to Make Cleaner Code as a Developer

Photo by Luca Bravo on Unsplash

I used to think that good code involved adding a lot of detailed comments.

After reading Robert C. Martin's book titled Clean Code, I realised I was using comments in the wrong way.

Here are the reasons why:

Limit your use of comments, explain yourself in code instead

Comments tell lies, code does not.

Comments are used to explain what the code does, but if they are not used correctly, they can spread misinformation about the code. Here’s how:

1. Bad explanations — The comment does not explain what the code does. Confusing the reader, and making them interpret the code for something else.
2. Time — When you first write a function, you put a comment to state exactly what the function does. If the codes functionality changes, the likely scenario is the comment never gets updated. Meaning the comment is now a lie.

Code does exactly what it says. Code may be hard to interpret, but it never lies.

That’s why it is vital to use good naming conventions and formatting, to make code easy to read and interpret.

Look at the following examples: