As developers, it’s been drilled into our heads that we must provide documentation for our programs … both inside the code, as comments, and for end user’s use.
One thing I’ve noticed that we tend to neglect, however, is to document the DECISIONS we make. Why did we select one implementation over another.
Case in point:
Last week, a co-worker and I were looking at some code that was written a few weeks ago … the code was clearly wrong, and the correct implementation was obvious to both of us. The problem is: we both remembered discussing this particular implementation … and we know that the decision not to implement it in the ‘obvious’ way was rejected. Unfortunately, neither of us could remember WHY that implementation was rejected.
Obviously, if we had documented the various implementations we had considered … and why we rejected or selected them, it there would have been a lot less head scratching.