because cleanliness
Part of a series of posts that discuss justifications for spending more time on a specific piece of code, rather than continuing onward.
The cleanliness justification for polishing code goes something like this:
This bit of code does what it’s supposed to do according to the requirements. However, I don’t like the way it’s organized. There are incomplete TODOs and unnecessary comments strewn about. There’s a class I could extract from this script that would make the script shorter. I should really clean this up — I can do better.
When does cleanliness mislead us?
The preference for cleanliness fails us when we fail to remember the lessons of opportunity cost. To put it another way: speed to market vs polish.
Why do we forget, or ignore, the lessons of opportunity cost?
Personality traits
It’s been my observation that part of what attracts many engineers to the discipline is the sense of order that code can provide. It literally produces a feeling of comfort and control over one’s environment to not only write working code, but to have it read a certain way when it’s finished.
Explicit reinforcement training
Formal education or training, feedback from other engineers, and the values and traditions extolled by others in our industry: repeatedly reinforced over time, unquestioned, can result in a mental shortcut that causes us to believe that almost all cleanliness and organization is worthwhile when it isn’t.
Predicting the future
We often try to justify cleanliness because of a predicted future state, such as:
- Next time we touch this code, it will be faster if we just clean it up now
- If I generalize this, we can reuse it anytime we need, and therefore it’s worth it
This way of thinking is the opposite of a principle that seems to work much better: YAGNI.
When is cleanliness helpful?
Very rarely, and only if it happens at the point at which the code is originally written. In my experience on teams, cleanliness is almost never helpful unless:
- The cleanup happens as part of a PR review, before it’s merged
- The cleanup is so low-cost that it can be done in minutes, rather than hours or days (PR feedback with a working patch is even better)
Rather than trying to find the most clean way to do something, it is usually better to simply write the software differently the next time we have to solve a similar problem, than to go back and clean it up once it’s already out there, working, and relied upon to be stable.
