Code Smell 05 — Comment Abusers

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

Maximiliano Contieri

Oct 24, 2020

Photo by Volodymyr Hryshchenko on Unsplash

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.

What exactly is a name - Part I The Quest

Refactorings ⚙️

Refactoring 005 - Replace Comment with Function Name

Refactoring 011 - Replace Comments with Tests

Refactoring 002 — Extract Method

Maximiliano Contieri

November 25, 2021

TL;DR: Group your cohesive sentences together

Read full story

Examples

Libraries
Class Comments
Method Comments

Context 💬

You write comments when you feel your code does not speak by 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 👩‍🏫

Conclusion 🏁

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

Relations 👩‍❤️‍💋‍👨

Code Smell 75 - Comments Inside a Method

Code Smell 57 - Versioned Functions

Code Smell 168 - Undocumented Decisions

Code Smell 151 - Commented Code

Code Smell 183 - Obsolete Comments

Code Smell 146 - Getter Comments

More Information 📕

Refactoring Guru

What is in a name

Comments as a bad sign

How to comment your code

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