Don't write comments

Code comments are code smells

Daniel Moka

Feb 03, 2025

Are you ready to master clean code, testing and Test-Driven Development (TDD)?

I recently launched a complete TDD course containing everything you need to craft high-quality software.

Now there is a 50% OFF for the course

Get instant access by clicking here.

Get Instant Access

Motivation

Code comments are code smells. Period. Developers think they make the code more descriptive with comments, but most times it just results in redundant, noisy and outdated information.

There are exceptions when comments make sense, but most times we can get rid of them by using clean design. First, let's look at the problems that comments create, then let’s see when they are useful tools to achieve clean code.

The problems

❌ Comments become easily outdated and rotten

Code changes frequently, but comments often don’t get updated. This often leads to misleading information, where the comment says one thing, but the code does another. Outdated comments are worse than no comments because they create confusion and misguide developers.

This comment describes fetching all active and VIP customers, but the actual code retrieves all VIP customers, including inactive ones. If the query logic changes but the comment isn’t updated, developers reading the comment are misled.

❌ Nobody reads excessive comments

Comments should add value, not state the obvious. When every other line is a comment, developers tend to ignore them altogether. Over-commenting can clutter the codebase, making it harder to read and maintain.

The large volume of comments can decrease their value, turning them into noise rather than helpful annotations:

❌ Comments are never executed

Comments don’t affect how the code runs. They are static text that can be incorrect, leading to confusion and bugs. Since the compiler doesn't check them, mistakes in comments can easily go unnoticed.

This comment claims the function converts Fahrenheit to Celsius, but the actual formula converts Celsius to Fahrenheit. Because comments aren’t executed, this mistake won’t trigger an error—leading to incorrect assumptions and potential bugs.

When Comments Are Useful

While comments are generally discouraged, there are specific scenarios where they aren’t only useful but necessary:

✅ Explaining the why

Sometimes, the reasoning behind a piece of code isn’t immediately apparent. In such cases, a brief comment explaining the motivation can be invaluable. This helps future maintainers understand the context and rationale behind certain decisions.

This comment explains the reasoning behind rounding to two decimal places to prevent transaction errors.

✅ API doc generation

Comments play a crucial role in API documentation, helping users understand how to use the API effectively. Clear documentation improves usability and adoption, making our system more developer-friendly:

✅ Revealing implicit behaviors

Behaviours of the code aren’t always immediately obvious. In such cases, a comment can clarify implicit behaviors, helping others understand nuances and avoid pitfalls.

For example, a library may handle retries automatically:

This comment explains an implicit behavior of the library (retry mechanism) that isn’t immediately apparent in the code.

✅ Referring to resource

When relevant external sources exist, it’s better to refer to them in a comment, especially for complex math formulas and calculations:

This directs the developer to the authoritative source for detailed rules, ensuring consistency.

Summary

Apart from these exceptions, don't write comments. Use intention-revealing names instead. Refactoring is your friend.

Avoiding comments is just one aspect of writing clean code. My TDD course covers this and much more—helping you become a professional developer who writes quality software confidently.

What you get: