The code has lots of comments. Comments are coupled to implementation and hardly maintained. 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. TL;DR: Leave comments just for important design decisions. Don't explain the obvious. Problems 😔 Maintainability
Obsolete Documentation
Readability
Duplication between code and comments 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. 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. 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 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://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true https://maximilianocontieri.com/refactoring-011-replace-comments-with-tests?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 https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true Examples Libraries
Class Comments
Method Comments 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
    }
} <?

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() {
    }
} <?

final class ChatBotConnectionSequenceGenerator {

    function connectionSequence() {
    }
} Detection 🔍 [x]Semi-Automatic [x]Semi-Automatic [x] Linters can detect comments and check the ratio of comments to lines of code against a predefined threshold. Tags 🏷️ Comments Comments Level 🔋 [x]Beginner [x]Beginner [x] 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 Remember: AI Assistants make lots of mistakes Suggested Prompt: Convert it to more declarative 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 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 Without Proper Instructions

With Specific Instructions Without Proper Instructions Without Proper Instructions With Specific Instructions With Specific Instructions ChatGPT

ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT ChatGPT Claude

Claude Claude Claude Claude Claude Claude Claude Perplexity

Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Perplexity Copilot

Copilot Copilot Copilot Copilot Copilot Copilot Copilot You

You You You You You You You Gemini

Gemini Gemini Gemini Gemini Gemini Gemini Gemini DeepSeek

DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek DeepSeek Meta AI

Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Meta AI Grok

Grok Grok Grok Grok Grok Grok Grok Qwen

Qwen Qwen Qwen Qwen Qwen 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-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-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-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-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-xxxvii https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx 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://refactoring.guru/es/smells/comments?embedable=true https://hackernoon.com/what-exactly-is-a-name-the-quest-part-i-fmw3udc?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://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 https://arter.dev/how-to-comment-your-code-like-a-boss?embedable=true Credits Photo by Volodymyr Hryshchenko on Unsplash Volodymyr Hryshchenko 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. 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 Martin Fowler https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true 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 https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true

Unsplash

Refactoring 033 - Removing Redundant or Unused Annotations

Buy My Book

Code Smell 05 - Comment Abusers

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Untitled Story

10 Predictions About the Future of Finance

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

110 Stories To Learn About Refactoring

3 Things Coding And Prose Writing Have In Common According To Cory House

10 Predictions About the Future of Finance

106 Stories To Learn About Clean Code

100 Pieces of Programming Advice from the Book Clean Code by Robert Martin

110 Stories To Learn About Refactoring

3 Things Coding And Prose Writing Have In Common According To Cory House

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps