The advice from this post is exactly what you’d expect in theory and exactly “what not to do” in practice. For one simple reason: the source code is (hopefully) the only thing pretty much guaranteed to survive.
I have seen countless shops where valuable history was lost because it was stored on someone’s c: drive, a network drive, or some repository that failed to survive some kind of migration. And even if these other files (digital or paper) did survive, chances are that the programmer that needed to see them never did anyway.
Good shops practice keeping audit trails “in the source code”. This means good commenting. Which means good code review and quality control.
I recently came across a single piece of code that had been changed back and forth 6 times in the previous 2 years. The comments looked something like:
* jeo 02/11/09 Use Ship Date, not Book Date per Sarah in Sales
* jrm 04/15/09 Use Book Date to make military contracts balance
* msl 08/24/09 Use Ship Date per Joe in Ops (military no longer active)
* jrm 12/13/09 Use Book Date per Rick Smith to prepare for new contracts
* jrm 02/14/10 Use Ship Date per Rick Smith after Ops meeting
* jrm 05/25/10 Use Book Date per Rick Smith until Q3 migration
I know that this is an extreme example, but this stuff happens all the time in commercial environments. How easy do you think it would be for the programmer/analyst to provide background if these comments were not in the source code, but somewhere else?
Sure it’s a pain it the ass to maintain this, but it immediately provides the needed background to the person who needs it, when he needs, where he’s already working. For critical projects with confused users (what isn’t), the alternative is usually much more work.