What's the purpose of internal project documentation? To help people do their jobs. Developers need the knowledge to be distributed across the team, testers need definition of proper system behaviour, marketing needs information on product features to sell it.
Important knowledge that may be required by developers doing updates may be summarized in few sentences:
- Who changed recently that line of code?
- When this method have been changed?
- Why algorithm works that way?
There's simple method of automatically saving and retrieving this kind of information: Subversion (or any other version control system). How?
There's nice feature of version control system that is not the most frequent used but is very useful: annotation/blame. This special view shows you for a file:
- Who changed this line?
- When this line was changed?
- Revision number of commit => Log entry => Bug tracker task ID => rationale (Why)
After locating such information you may have better understanding of source code.
How to check annotation using different tools:
- svn annotate filename
- git annotate filename
- bzr annotate filename
- Eclipse: Team / Show Annotation
Looks simple, but there's a "quirk" here. If you are doing massive code changes (to enforce n+1th coding standard) you are overwriting original source code authors and information. Thus annotation (and log) becomes useless.
That's why I'm asking you:
Do not reformat whole files on commit, PLEASE!