TL; DR; should we keep a log of design decisions, and then look back at them? Would it pay off?
We spend a lot of time trying to analyse investment decisions; we gather documents, get multiple opinions, store extensive data on the subject and retrospect on that data over many years.
However, we don’t really do that on designs for systems.
We might, if we are good, do a project retrospective, but how often do we do a design decision retrospective? How long a time frame do design decisions have an impact?
Who made this? were they drunk?
It’s so common to come to a new system and criticise it, why did they do that?
- why does this table have so many columns?
- Why didn’t they simplify this design?
- (conversely..) Why didn’t they make the design have more options for flexibility?
- Why did they name that variable like that?
- why did they use this untested technology that no one else uses?
- (conversely) why did they use this old legacy technology that we now want to get rid of?
We should probably give them the benefit of the doubt, if it looks complicated: maybe that’s not that the person didn’t “get it”, but that they “got” something else that we don’t see yet.
Coding it right next time
Many times when we start out on a system, we remember what happened last time and are determined not to fall into the same trap. You don’t start each game of software with a clean board (see Software architecture as a chess game, with yourself) you have to start with what you know now, not with what you’ll know in 2 years’ time.
So this time you put in an extra layer of abstraction, because last time you had to do all sorts of bolt-ons…. but this time you end up not needing it and spend 10 years stepping over this abstraction layer where every class has exactly 1 implementation (or anything else, could be a database table or an enum or whatever)… But you don’t figure out that that extra layer isn’t needed – is never needed – for 10 years.
Reflection, using a design decision log
So how to close that learning loop? it’s 10 years long for pete’s sake, how are we going to do that? We can’t wait 10 years to reflect, because tech has moved on (a bit) and you have changed (a lot) so how do we do it?
I think that a decision journal would be a great thing to do, but it’s very hard to get started. Investment decisions are easy in that respect; you know that one day that buy will become sell and you’ll be at an end, all decisions follow the same course, eventually. But design choices are harder to squeeze into the same format.
Maybe that’s why we keep making the same errors, we have to wait until architects get sad and leave the industry and become academics to document other people’s problems and (maybe) teach the next generation to avoid them..?
Does anyone already do this?
in public: https://adr.github.io/ : lightweight architectural decision records.
I can see a few examples of this kicking around in my corporate setting, but mostly they look like project retrospectives. I wonder if we could scoop them up and put them in a binder and call it “the wisdom of the ancients”.
But, before you can hear the lesson, you must have learned the lesson?
No More Hacks 