Why You Shouldn't Overuse Comments

Introduction

Comments in code are often seen as a great practice to aid understanding.
But if you're familiar with Clean Code by our famous Uncle Bob, you know he takes a very different stance.

In this cult classic, Uncle Bob offers a minimalist approach to comments.
He argues that the best code is the one that doesn't need comments.

So, why would an expert like him go against what many consider a great practice?
Let's explore the reasons behind this radical approach and think about when and how comments are truly justified.

Code Should Be Self-Explanatory

The first key idea is that code should speak for itself.
If you need a comment to explain what your function or variable does, it’s often a sign that the code itself isn't clear enough.
The goal is to name variables and functions in such a way that their purpose is immediately understandable.

// increments the loop index
i++

Here, the comment doesn't add any useful information. We don't need an additional explanation to understand what this line of code does.

In clean code, variable names like totalItems, incrementIndex, or isLoggedIn already tell a story.
The intention is immediately clear.

Comments Often Become Outdated

Another major issue raised by Uncle Bob is that comments don’t age well.
As the code evolves, it's common to forget to update the corresponding comments.
This can create a situation where the comment is lying, meaning it describes a behavior of the code that no longer exists.

This is not only confusing, but it also harms the overall readability.
A developer relying on the comment to understand a feature may be misled.

Unnecessary Comments Add Clutter

One of the worst uses of comments, according to our famous Uncle, is using them to restate what the code already makes clear.
Comments like :

// opens the file
File file = new File("data.txt");
file.open();

This adds no value and, in fact, makes the code heavier to read.
By cluttering the file with unnecessary comments, we create an environment where the essential code becomes harder to spot and understand.

When Comments Are Actually Useful

That said, Uncle Bob doesn’t advocate for the complete removal of comments.
He recognizes that some contexts require more detailed explanations.

For example:

• Contextualizing a complex decision :
  If a particular approach was chosen to solve a technical problem or to work around a limitation, a comment might be justified to explain that decision.

• External references :
  When code depends on a bug or a specific behavior of an API or external system, a comment can provide valuable context to understand why the code was written in that way.

// This method uses a workaround to avoid bug #1234 in the XYZ external library

For example, this kind of comment is useful :-)

This type of comment helps future colleagues understand non-obvious decisions without having to dig through support tickets or other sources.

Clean Code Is Better Than Comments

The main takeaway from Clean Code is simple: instead of commenting your code, write it cleanly from the start.
Comments should never be a crutch to make up for poorly designed code.
Well-structured, readable, and maintainable code will naturally reduce the need for additional explanations.

If a comment is necessary, it’s often a sign that something in the code can be improved.

Conclusion

Comments in code, while useful in certain cases, are not a magic solution to make code more understandable.
The key lies in the clarity and simplicity of the code itself.
Clean, well-structured, and self-explanatory code minimizes the need for comments and contributes to better long-term maintainability of the project.

Uncle Bob’s message is clear: write clean code, comment wisely.