DEV Community

Cover image for Code Smell 183 - Obsolete Comments
Maxi Contieri
Maxi Contieri

Posted on • Originally published at maximilianocontieri.com

2

Code Smell 183 - Obsolete Comments

Comments are a code smell. Obsolete comments are a real danger and nobody maintains what can't be executed.

TL;DR: Don't trust comments. They are dead.

Problems

  • Bad documentation

  • Maintainability

Solutions

  1. Replace comments with tests

Refactorings

Context

We know comments add almost no value to our code.

We need to restrict comments only to very important decisions.

Since most people change logic and forget to update comments they might become obsolete easily.

Sample Code

Wrong

void Widget::displayPlugin(Unit* unit)
{

    // TODO the Plugin will be modified soon, so I don't implement this right now

    if (!isVisible) {
        // hide all widgets
        return;
    }

}
Enter fullscreen mode Exit fullscreen mode

Right

void Widget::displayPlugin(Unit* unit)
{ 
    if (!isVisible) {
        return;
    }
}
Enter fullscreen mode Exit fullscreen mode

Detection

[X] Semi-Automatic

We can warn for comments in our code and try to remove them.

Exceptions

  • Very important design decisions

Tags

  • Comments

Conclusion

We need to think before adding a comment. Once It is in the codebase is beyond our control and can start to lie anytime.

Relations

Disclaimer

Code Smells are just my opinion.

Credits

Photo by Volodymyr Hryshchenko on Unsplash


Obsolete comments tend to migrate away from the code they once described. They become floating islands of irrelevance and misdirection in the code.

Bob Martin


This article is part of the CodeSmell Series.

Image of Docusign

🛠️ Bring your solution into Docusign. Reach over 1.6M customers.

Docusign is now extensible. Overcome challenges with disconnected products and inaccessible data by bringing your solutions into Docusign and publishing to 1.6M customers in the App Center.

Learn more

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

👋 Kindness is contagious

Please leave a ❤️ or a friendly comment on this post if you found it helpful!

Okay