Commit Comments: A Conversation with your Future Self

I frequently find myself searching subversion commit logs trying to find hints as to why certain "features/bugs" where introduced and why. Usually this results in wasting several hours and almost every time I get frustrated with a lack of dialogue in commit comments. I can't stress enough the importance of this often over looked feature when committing changes. A lot of developers look at it like a 30 second burden that's preventing them from taking lunch earlier. What they really should be doing is pretending it's a conversation with their future self. Six months from now you're most likely going to be seeing those comments, or lack of, wondering why you made that change. It's in that moment I'd rather have a very descriptive summary of what changed and why verses diff'in every version known to man.

I'm not asking for a Kevin Costner script, just be a little more specific. On average, my comments are 1-3 sentences. For the important changes, I've used paragraphs before. Comments with fewer than 5 words drive me nuts, and I have seen a lot of them.

Ever seen a movie where campers make a trail using something like marshmallows so they can find their way back? Think of your commit comments like marshmallows helping you unravel the mystery of an issue and start developing the habit of providing more descriptive commit comments.

Other Useful Tools
One of the tools I have grown fond of is the Jira subversion plugin. Our team uses Jira as our issue tracking system. Nothing gets committed without a Jira number. This is enforced using a subversion pre-commit hook, so every developer has to start their comment with a Jira number. Then in Jira, there is a Subversion Commits link at the bottom to where anyone can view the files changes and their comments.

Using the subversion pre-commit hook has another added bonus, which is using the Hudson Jira Plugin. After a successful build, hudson will extract the Jira number(s) from the commit comments and add a comment to the Jira stating it was integrated at a specific build # and includes a link.