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

Replace comments with tests

Refactorings

Refactoring 005 - Replace Comment with Function Name

Maxi Contieri ・ Jun 7 '22

#javascript #beginners #refactorit #programming

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;
    }

}

Right

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

Detection

[X] Semi-Automatic

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

Exceptions

Very important design decisions

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

Code Smell 05 - Comment Abusers

Maxi Contieri ・ Oct 24 '20

#codenewbie #tutorial #beginners

Code Smell 152 - Logical Comment

Maxi Contieri ・ Jul 24 '22

#javascript #webdev #beginners #programming

Code Smell 151 - Commented Code

Maxi Contieri ・ Jul 22 '22

#javascript #webdev #beginners #programming

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

Software Engineering Great Quotes

Maxi Contieri ・ Dec 28 '20

#codenewbie #programming #quotes #software

This article is part of the CodeSmell Series.

How to Find the Stinky parts of your Code

Maxi Contieri ・ May 21 '21

#codenewbie #tutorial #codequality #beginners

Code Smell 183 - Obsolete Comments