Bitcoin

Code Smell 05 – Comment Abusers

mrarup82September 4, 2025

0 0 2 minutes read

The code has lots of comments. Comments are coupled to implementation and hardly maintained.

TL;DR: Leave comments just for important design decisions. Don’t explain the obvious.

Problems 😔

Maintainability
Obsolete Documentation
Readability
Duplication between code and comments

Solutions 😃

Refactor methods.
Rename methods with more declarative names.
Break down large methods.
If a comment describes what a method does, name the method with this description.
Just comment on important design decisions.

https://hackernoon.com/what-exactly-is-a-name-the-quest-part-i-fmw3udc?embedable=true

Refactorings ⚙️

https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true

https://maximilianocontieri.com/refactoring-011-replace-comments-with-tests?embedable=true

https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true

Examples

Libraries
Class Comments
Method Comments

Context 💬

You write comments when you feel your code does not speak for itself.

\
Most of the time, you add noise instead of clarity.

\
Later, those comments lie when you change the code but forget to update the explanation.

\
Instead of helping, they hurt.

Sample Code 📖

Wrong 🚫

<?

final class ChatBotConnectionHelper {
    // ChatBotConnectionHelper is used
    // to create connection strings to Bot Platform
    // Use this class with getString() function
    // to get connection string to platform

    function getString() {
        // Get Connection String from Chatbot
    }
}

Right 👉

<?

final class ChatBotConnectionSequenceGenerator {

    function connectionSequence() {
    }
}

Detection 🔍

[x] Semi-Automatic

Linters can detect comments and check the ratio of comments to lines of code against a predefined threshold.

Tags 🏷️

Comments

Level 🔋

[x] Beginner

Why the Bijection Is Important 🗺️

Your software should reflect the domain with no translators in between.

\
When you use comments as crutches, you break the one-to-one mapping between the real-world concept and its code representation.

\
This mismatch creates confusion and bugs.

AI Generation 🤖

AI tools often generate comments to explain code in natural language.

\
This can pollute your source when the code already speaks for itself.

AI Detection 🧲

AI tools can easily remove redundant comments and suggest clearer names.

\
You only need to instruct them to “remove obvious comments and refactor for clarity.”

Try Them! 🛠

Remember: AI Assistants make lots of mistakes

Suggested Prompt: Convert it to more declarative

Conclusion 🏁

Leave comments just for important design decisions. Don’t comment on a method with a bad name; rename it.

Relations 👩‍❤️‍💋‍👨

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xv

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxi

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxvii

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx

More Information 📕

https://refactoring.guru/es/smells/comments?embedable=true

https://hackernoon.com/what-exactly-is-a-name-the-quest-part-i-fmw3udc?embedable=true

https://dev.to/alexbunardzic/code-comments-are-a-sign-that-something-s-off-19e1?embedable=true

https://arter.dev/how-to-comment-your-code-like-a-boss?embedable=true

Credits

Photo by Volodymyr Hryshchenko on Unsplash

If you have to spend effort looking at a fragment of code and figuring out what it’s doing, then you should extract it into a function and name the function after the what.

Martin Fowler

https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true

This article is part of the CodeSmell Series.

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true