Code Smell 168 - Undocumented Decisions

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

Maxi Contieri
·Oct 11, 2022·

1 min read

Subscribe to my newsletter and never miss my upcoming articles

Play this article

Table of contents

  • Problems
  • Solutions
  • Context
  • Sample Code
  • Detection
  • Tags
  • Conclusion
  • Relations
  • Disclaimer
  • Credits

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

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

 
Share this