Technovangelism

As I approach the end of a development project, I am becoming more and more aware of worthless documentation. Our dev team made an agreement with our client about the documentation that would be provided when we transition the project. Because of this, I have been examining all of the different documentation being provided and doing my best to strip out the cruft. The latest goldmine of not so helpful comments I have found is version control logs, especially when combined with fix messages on your bug tracking system.

The problem, as I keep saying, is finding any actual value in them. After looking through my team’s latest commits, I spent more time viewing the actual differences in the source than the messages provided alongside. After a few minutes of this, I began to look for the ideal commit message, and finally decided that one does not exist. All of your commits should be tied to a bug/issue/feature in your tracking software, and your messages are better made there. By only writing messages in your tracking software, you will never duplicate the same message in your source control logs. Even better, there are probably more people involved in your development process than just developers and other “code touchers” (one who checks out the code from source control). The non code touchers are very unlikely to see commit messages, and could potentially lose out of some important information tucked away in subversion.