readme.md

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

1. Be Explicit about the reasons.

2. 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

// You 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

Code Smell 05 - Comment Abusers

Code Smell 75 - Comments Inside a Method

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