Monday, March 14, 2011

Why Commit Comments Matter

Lets look at something pretty basic: Commit comments. Why are they important? -Good commit comments should summarize the context and intent of the commit. Writing good commit comments gives you a better version history and gives you better individual commits. Lets look at each of these claims in turn.

Better Version History
Good commit comments makes the version history better in a number of ways:

  • Having commit comments that summarize intent turns the commit history of the previous day into a quick way for team members to check what happened in the code base yesterday - and they can readily drill down into the code diffs if they want.
  • Having commit comments that summarizes the context of the commit - e.g. by including a bug report number or a user story id - is a very simple and flexible way to introduce traceability from code to requirements.  
  • Having commit comments that summarize the context and the intent is an excellent tool for understanding code later on: When something seems to work, but also seems a bit odd, it is great to be able do an svn blame or git blame and get an idea of the context and intent behind that code.

Better Individual Commits
Writing good commit comments requires just a little bit more thought than writing no comment or writing a non-comment like "checking in code" or "bugfixes" or "I'm going home now". That little bit of extra thought is quite often just enough to make you realize if your commit could break that other part over there, or that you haven't run all the relevant tests, or that it just isn't one cohesive whole and should be split into two or three individual commits. That last point can also lead you to committing more often, and as a result synching and integrating with the rest of the team more often. Good cycle.

But I'm In a Hurry
Yeah, well we all are. So don't waste teammates time by breaking the build or having them read through the version history diff by diff just so you save a commit comment. Besides writing good commit comments really doesn't take long. Seriously we're talking 10 seconds. Just pick a format and stick to it. I like
<task id>: <Main intent>. <Important technicalities>
 That's quick to write, right?