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

• A file with a special name in the code repository (say Log). Log is intended to be used as a journal as we work on the codebase.
• An editing environment that does the following everytime Log is saved:
  • Commits the codebase (saves a snapshot)
  • Appends a tag and timestamp to Log identifying the snapshot
• A command to extract the snapshot corresponding to a given tag.

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.