# Code Smell 168 - Undocumented Decisions

> 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

[Gist Url]: # (https://gist.github.com/mcsee/554144e5e61703b8a556328671b0a3dd)
```c
// We need to run this process with more memory
set_memory("512k)
           
run_process();           
```

## Right

[Gist Url]: # (https://gist.github.com/mcsee/ab76cec5efd320d5cf9a2e626343d3e8)
```c
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

%[https://maximilianocontieri.com/code-smell-05-comment-abusers]

%[https://maximilianocontieri.com/code-smell-75-comments-inside-a-method]

# Disclaimer

Code Smells are just my [opinion](https://maximilianocontieri.com/i-wrote-more-than-90-articles-on-2021-here-is-what-i-learned).

# Credits

Photo by [Goh Rhy Yan](https://unsplash.com/@gohrhyyan) on [Unsplash](https://unsplash.com/s/photos/warning)
  
* * *

> 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_
 
%[https://maximilianocontieri.com/software-engineering-great-quotes]

* * *

This article is part of the CodeSmell Series.

%[https://maximilianocontieri.com/how-to-find-the-stinky-parts-of-your-code]