The traditional prescription for keeping software easy to work with and amenable to change is “refactoring”. As we’re fixing bugs, adding features, and making new possibilities, we investigate how to change the structure of code so that correcting, changing, or adding behavior is easier. In reverse order — we should make the change easy, then make the easy change to achieve the desired results1.
I may not surprise you in suggesting that’s often not how things actually work out.
Some code, processes, or data are inherently complex or crystalized in path dependence. After our first urge to simplify is stymied, move on to the second possibility: live with and document the complexity, then keep moving2. Everyone wins.
Documenting code is a great forcing function for simplifying it. When I look at code with the intent of writing down how to use or understand it, my perspective shifts, and I’m more aware of the missing affordances. A clarifying parameter name or perhaps a simpler calling sequence. So I make that change (aka refactoring) as part of the process of documenting the code. Everyone wins.
The same goes for processes and data. Writing down how to fix an unprocessed payment or restore data after an accidental deletion flips my perspective enough that I’m not seeing it in the weeds. I can see opportunities for automation, so I take them. Or I can see how to improve a data structure such that errors are obvious to humans or detectable by computers. I make that change, everyone wins.
It’s not always possible to find these little wins. Occasionally, we don’t win!
Some systems, especially the older and critical ones, resist change. The volume of data may be the resistance to change, the process may touch too many people to casually change, the risk of updating code may be too great. If you’ve worked on a billing system, I bet you’re hallucinating memories of it at the mere mention of data, process, people, and code resisting even the smallest change in course.
In that case, the next best way to improve the situation is to improve everyone’s knowledge of the system by writing it down. Document how it works. Even better, elaborate on how it’s supposed to work and how it actually works in some important but problematic circumstances.
Go from tricky code to refactoring. If you’re stymied by refactoring, switch to documenting it instead. Everyone wins.
