Code Smell 05 - Comment Abusers

Written by mcsee | Published 2025/09/03
Tech Story Tags: refactoring | clean-code | code-smells | programming-tips | fixing-code-smells | comment-abusers | refactor-methods | programming-tips-and-tricks

TLDRLeave comments just for important design decisions. Don't explain the obvious.via the TL;DR App

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 πŸ˜ƒ

  1. Refactor methods.
  2. Rename methods with more declarative names.
  3. Break down large methods.
  4. If a comment describes what a method does, name the method with this description.
  5. 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

Without Proper Instructions

With Specific Instructions

ChatGPT

ChatGPT

Claude

Claude

Perplexity

Perplexity

Copilot

Copilot

You

You

Gemini

Gemini

DeepSeek

DeepSeek

Meta AI

Meta AI

Grok

Grok

Qwen

Qwen

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


Written by mcsee | I’m a sr software engineer specialized in Clean Code, Design and TDD Book "Clean Code Cookbook" 500+ articles written
Published by HackerNoon on 2025/09/03