DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

Cover image for Code Smell 168 - Undocumented Decisions
Maxi Contieri ⭐⭐⭐
Maxi Contieri ⭐⭐⭐

Posted on • Originally published at maximilianocontieri.com

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

// We need to run this process with more memory
set_memory("512k)

run_process();           
Enter fullscreen mode Exit fullscreen mode

Right

increase_memory_to_avoid_false_positives();
run_process();      
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (2)

Collapse
 
theaccordance profile image
Joe Mainwaring

I thought this article was going to focus on establishing ADRs over simply renaming functions as documentation

Collapse
 
mcsee profile image
Maxi Contieri ⭐⭐⭐

you mean architectural decision record?
is that decision on code or on external sources?

Join us at DEV
Yes, this is technically an β€œad”, but really we just want to ask if you want to join DEV. We have 900k+ developers reading, posting, and enjoying community, and would love to have you. Β  Create an account and continue your coding journey.