The code has lots of comments. Comments are coupled to implementation and hardly maintained.
TL;DR: Leave comments just for important design decisions. Don't explain the obvious.
Problems π
- Maintainability
- Obsolete Documentation
- Readability
- Duplication between code and comments
Solutions π
- Refactor methods.
- Rename methods with more declarative names.
- Break down large methods.
- If a comment describes what a method does, name the method with this description.
- Just comment on important design decisions.
https://hackernoon.com/what-exactly-is-a-name-the-quest-part-i-fmw3udc?embedable=true
Refactorings βοΈ
https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true
https://maximilianocontieri.com/refactoring-011-replace-comments-with-tests?embedable=true
https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true
Examples
- Libraries
- Class Comments
- Method Comments
Context π¬
You write comments when you feel your code does not speak for itself.
Most of the time, you add noise instead of clarity.
Later, those comments lie when you change the code but forget to update the explanation.
Instead of helping, they hurt.
Sample Code π
Wrong π«
<?
final class ChatBotConnectionHelper {
// ChatBotConnectionHelper is used
// to create connection strings to Bot Platform
// Use this class with getString() function
// to get connection string to platform
function getString() {
// Get Connection String from Chatbot
}
}
Right π
<?
final class ChatBotConnectionSequenceGenerator {
function connectionSequence() {
}
}
Detection π
- [x]Semi-Automatic
Linters can detect comments and check the ratio of comments to lines of code against a predefined threshold.
Tags π·οΈ
- Comments
Level π
- [x]Beginner
Why the Bijection Is Important πΊοΈ
Your software should reflect the domain with no translators in between.
When you use comments as crutches, you break the one-to-one mapping between the real-world concept and its code representation.
This mismatch creates confusion and bugs.
AI Generation π€
AI tools often generate comments to explain code in natural language.
This can pollute your source when the code already speaks for itself.
AI Detection π§²
AI tools can easily remove redundant comments and suggest clearer names.
You only need to instruct them to "remove obvious comments and refactor for clarity."
Try Them! π
Remember: AI Assistants make lots of mistakes
Suggested Prompt: Convert it to more declarative
Without Proper Instructions |
With Specific Instructions |
---|---|
Conclusion π
Leave comments just for important design decisions. Don't comment on a method with a bad name; rename it.
Relations π©ββ€οΈβπβπ¨
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xv
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xii
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiv
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxi
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxvii
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxx
More Information π
https://refactoring.guru/es/smells/comments?embedable=true
https://hackernoon.com/what-exactly-is-a-name-the-quest-part-i-fmw3udc?embedable=true
https://dev.to/alexbunardzic/code-comments-are-a-sign-that-something-s-off-19e1?embedable=true
https://arter.dev/how-to-comment-your-code-like-a-boss?embedable=true
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
https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true
This article is part of the CodeSmell Series.
https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true