Recording Design Decisions (not)
Laurent Bossavit is writing about Recording design decisions. I gave up on the idea of recording (all) design decisions years ago, when I was doing research into that topic at the University of Twente, together with Marc Evers. We tried to come up with a formal model that would trace each decision back to a corresponding piece of code. The complexity of instances of that model was mind-boggling, especially if you start taking the evolution of source code over time into account.
We came to the conclusion, that the number of decisions involved in creating any computer program is too large to record meaningfully. Another conclusion we arrived at, was that many decisions are made at lightning speed inside our head, and some decisions we are unable to articulate. I think that is one of the underlying reasons attempts at documenting software in detail often fail (besides the fact that very few software people enjoy writing prose).
One thing I usually do when working with a team, is to regularly (every hour at least) check in code to the version control system, and add a one-line comment when checking in. These comments reflect the closest practical thing I found to keep a trace of design decisions. I noticed after some time, that we rarely look back on the comments – I think it is because team members find it more effective to ask each other ‘why is this part built the way it is’, re-create the assumptions underlying the design by asking ‘why’, and either working from those assumptions, or re-defining the assumptions and start refactoring.
The best way I found to get design decisions out in the open is to do Pair Programming, so two programmers are forced to articulate a larger part of their design decisions. Even then, it is recommended practice to code out versions of an idea as a Spike Solution, if a discussion takes to long, and continue the discussion after two versions of the idea are complete: sometimes an idea is more easily expressed in source code than it is in natural language…
I’m asking myself: Why would I want to record design decisions?. I haven’t felt the desire to do that since leaving university. If the design is simple, and we keep requirements as automated acceptance tests, we are free to change the design whenever we want to. The acceptance tests provide the context we need to start finding appliccable (design) patterns. Perhaps the desire to record design decisions is an indicator we are building overly complicated software?
Rather than making an effort to record more design decisions, we can get leverage from simplifying our design and doing more automated acceptance testing.
