Photo by Goh Rhy Yan on Unsplash
Code Smell 168 - Undocumented Decisions
We need to make some changes. We need to be clear on why
TL;DR: Be declarative on your design or implementation decisions.
Problems
Code Comments
Lack of testability
Solutions
Be Explicit about the reasons.
Convert the comment to a method.
Context
Sometimes we find arbitrary rules not so easily testable.
If we cannot write a failing test, we need to have a function with an excellent and declarative name instead of a comment.
Sample Code
Wrong
// We need to run this process with more memory
set_memory("512k)
run_process();
Right
increase_memory_to_avoid_false_positives();
run_process();
Detection
[X] Semi-Automatic
This is a semantic smell.
We can detect comments and warn us.
Tags
- Comments
Conclusion
Code is prose. And design decisions should be narrative.
Relations
Disclaimer
Code Smells are just my opinion.
Credits
Photo by Goh Rhy Yan on Unsplash
Programs, like people, get old. We can’t prevent aging, but we can understand its causes, limit its effects and reverse some of the damage.
Mario Fusco
This article is part of the CodeSmell Series.