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.
David is a Principal Software Engineer for PTC, Integrity Business Unit. He cut his teeth on the S/36 and has more than 25 years of experience on the IBM i / System i / iSeries / AS400. He primarily works in Java and ILE RPG specializing in cross platform integrations. David has received the COMMON Distinguished Service award and was named an IBM Power Systems Champion. David is an active volunteer with the American Diabetes Association's Tour de Cure fundraising bike ride. He is currently captain of Team RED Chicago. David runs and maintains midrange.com. His personal blog is Geeky Ramblings.