Code Smell 05 - Comment Abusers
The code has lots of comments. Comments are coupled to implementation and hardly maintained.
30 July, 2022
4
4
0
Contributors
TL;DR: Leave comments just for important design decisions. Don't explain the obvious.
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 describes what a method does, name the method with this description.
5) Just comment on important design 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
Refactorings
More info
Tags
•
Comments
•
Declarative
Conclusion
Leave comments just for important design decisions. Don't comment on 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.