It’s all in your head
Pragmatic developers are constantly making trade-offs in the design of the code. Sometime they take on technical debt because it will be easier to pay it off later when things are clearer. The problem is what happens when they leave before they get a chance to pay off the debt and clear the backlog of ideas out of their head.
I know. Documentation is a four letter word for developers. But it doesn’t have to be. Yes the code should be self documenting but how do you document what the code could have been? How do you document the trade-offs and micro-decisions that led to the current code? In most cases this is left up to the maintaining programmer as they go spelunking in the depths of your code tryng to use software archaeology to unearth what the heck you were thinking when you wrote the code. In some systems only the penitent man shall pass. This Dr. Dobbs article on documenting micro-decisions provides a really simple idea. Track the decisions you make next to or in the code and make it part of your process. Then at least when you go back and re-read your code wondering what you were thinking there will be some context around the thought process you were going through.
Another effective practice is pair programming. In this case the knowledge is shared by at least two programmers and they can back each other up in the event the other is unavailable or cannot recall why they made the decision they did.
Capture it for yourself
If you use the documentation then you will see what makes it effective and what is a waste of time. Whenever you run into a question of why something is the way it is check your decision document. If it doesn’t have the answer then add it. It’s not a silver bullet and it’s not the sexy side of development but it’s simple enough to try out and determine if it’s worth adding it to your tool belt. Like TDD it seems like it would really pay off in frantic and chaotic environments. If you are a team leader then try asking your team to document the design decisions for a week and ask review them at the end of the week. It might also be a way to catch design mistakes and incorrect assumptions early in the process.
Edit: The problem with continuous learning is nothing is ever finished. No sooner do I post this then I finally get around to watching http://www.infoq.com/presentations/Decisions-Decisions by Dan North. It’s a great talk which confirms my opinion that if you can’t weigh the trade-offs of a decision then you are just guessing at things. Very few people seem to know why they do things the way they do. The rest seem to be fine cargo-culting (http://en.wikipedia.org/wiki/Cargo_cult) their way through a job.