This content originally appeared on Level Up Coding - Medium and was authored by Maximiliano Contieri
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
Software Engineering Great Quotes
This article is part of the CodeSmell Series.
How to Find the Stinky parts of your Code
Code Smell 168 — Undocumented Decisions was originally published in Level Up Coding on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Level Up Coding - Medium and was authored by Maximiliano Contieri
Maximiliano Contieri | Sciencx (2022-10-12T17:28:50+00:00) Code Smell 168 — Undocumented Decisions. Retrieved from https://www.scien.cx/2022/10/12/code-smell-168-undocumented-decisions/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.