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

Problems

• Maintainability

• Obsolete Documentation

• Readability

• Code and comments duplication.

Solutions

1) Refactor methods.

2) Rename methods to more declarative ones.

3) Break methods.

4) If a comment describe what a method does, name the method with this description.

5) Just comment important designs decisions.

Examples:

• Libraries

• Class Comments

• Method Comments

Sample Code

Wrong

Right

Detection

Linters can detect comments and check the ratio of comments / lines of code against a predefined threshold.

Relations

More info

Tags

• Comments

• Declarative

Conclusion

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

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

---

This article is part of the CodeSmell Series.