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();           

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

Maxi Contieri ・ Oct 24 '20

#codenewbie #tutorial #beginners

Code Smell 75 - Comments Inside a Method

Maxi Contieri ・ Jun 5 '21

#codenewbie #tutorial #oop #programming

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

Maxi Contieri ・ Dec 28 '20

#codenewbie #programming #quotes #software

---

This article is part of the CodeSmell Series.

How to Find the Stinky parts of your Code

Maxi Contieri ・ May 21 '21

#codenewbie #tutorial #codequality #beginners

Comments

[Joe Mainwaring]

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

[Maxi Contieri]

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