Say what your going to do — improve your commits

This one is a simple technique I’m using these days to improve the quality of my code. It stems from the way my mind works so may not be suitable for you, but its worth a try.

When I was younger I think my mind used a ‘heap’ for tracking my intended future state, so if I noticed something that needed doing I’d add it to the heap and then later I’d ‘rummage’ through it and find something that needed doing.

These days I find that if I don’t action something immediately it’s not guaranteed I’ll remember to do it later. My mind now seems to use a limited capacity ‘stack’ or ‘FIFO queue’ and if its capacity is exceeded then I don’t do the oldest items. On the other hand it does mean that things get done based on how long ago I have been reminded to do them.

This is not a blog post about that, its a blog post about the bad consequences of this change in how my mind works when coding and a solution to mitigate the effects.

The Bad Consequences

I get distracted, “Squirrel!”, and stop what I’m doing to work on the thing I have just noticed because if I don’t do it now I may forget to do it. This is fine most of the time but if I’m in the middle of a code change it means I ‘just’ fix the issue so that when I come to commit writing the commit comment is really hard as there are multiple things in the commit.

This means that if I need to revert to a previous version its very hard to isolate the main fix in the commit from all the other little tidy ups.

The Solution

Turned out to be absurdly simple.

Write your commit comment before you start coding

This focusses my mind, for example I’m just adding columns to the default view so if I see on a page that the field order is incorrect I don’t fix it. Instead I make a note, in the Source Code Control package, assign it an importance, and get back on with doing the work the commit is about.

In effect I have outsourced my brain’s ‘heap’ to a third-party.

Simple and for me alarmingly effective.