cover-img

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

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

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.

4

4

0

Maxi Contieri

Buenos Aires, Argentina

🎓Learn something new every day.📆 💻CS software engineer 👷coding👨🏽‍🏫teaching ✍🏾writing 🎨Software Design 🏢SOLID 🌉TDD 👴Legacy 💩Code Smells

More Articles

Showwcase is a professional tech network with over 0 users from over 150 countries. We assist tech professionals in showcasing their unique skills through dedicated profiles and connect them with top global companies for career opportunities.

© Copyright 2024. Showcase Creators Inc. All rights reserved.