A new way to commit

When writing exploratory code0, I often found myself forgetting to commit to version-control at the right places. Remembering to commit was turning into a burden that was making the Zone harder to find, and so turning me off version-control. And yet, it was illuminating to go over the big picture of the things I had tried. What I needed was a way to automate committing at just the right times.

But what are the right times? It's no use to commit on every time I save a code file — that's too frequent and leaves the history littered with versions that don't compile. It also gives no hint to the major milestones in a program's evolution. The answer I ended up with was to automatically commit whenever I had something coherent to say.

Automating the commit process

My current solution consists of the following components:1

Unanticipated benefits

After using it for a couple of years I find this process has several unanticipated benefits:
  1. I find myself committing much more frequently, and the changelog (for that is what Log is) is a lot more coherent, easy to read by itself.
  2. The extra context makes it much easier to find and drill down into the state of the repo at a specific point in the timeline.
  3. Anytime I find myself writing a large comment in the code I now think about whether to move it to the changelog. Just as accessible, and it reflects the fact that the comment is valid for a specific point in time.
  4. Once the larger comments move into the changelog I have a lot more confidence that my comments are not out-dated. As a result I find myself more inclined to write comments, which makes the changelog even more coherent and useful. It's a nice positive feedback cycle and a nice way to encourage oneself to document code.
  5. I focus more on leaving a trail of breadcrumbs and less on silly things like formal design documents and so on. It is the lesson of wikipedia: if you make the reader's job a little harder (validating what he reads with a little deduction, putting facts together from different commits), the writer is a lot more willing to give him meat to chew on.
Aug 2005


footnotes

0. Rather than more well-defined maintenance for a specific bug in an issue tracker.

1. Requires darcs and vim.