Think Before You Commit

One of my long-standing habits is to make an effort to maintain the source control history as neatly as I would like the code itself to be. You wouldn’t think this is very controversial, but looking at the public repos of some open source projects, it seems like a few people could stand to hear it. I call it the Think Before You Commit rule.

How I like to do it is, when I’m finished with something and think it’s ready to commit, start by taking a break. Get some coffee, browse the web for a bit, chat with somebody, take care of some other minor task, etc. The idea is to take your mind out of the moment of whatever you were working on. Then come back 5-10 minutes later, pull up the source control tool, and take a careful look at all of the diffs. As in look carefully through all of the diffs of every single file changed, even if you think you know what changed. Ask yourself the standard stuff like:

1. Do these changes all make logical sense to group together in a commit?
2. Has everything been refactored as much as reasonable? No ugly variable or method names, unused variables, reasonably well-organized, no commented-out code, etc.
3. Consider again whether this code actually does what you want it to do
4. If there are any unit tests associated with the changes, are they in the same commit?

Feel free to split things up into 2 or 3 commits or even a branch or two. It’s nice if you’re using a type of source control that actually makes that easy, like Git.

Once you’ve got all that set up, make sure to also write a good commit message. Ideally including what the code being committed does, why it does it that way, and any links or references to related bugs or work items in any tracking system that you’re using.

It might seem tedious or annoying at times, but it makes your code quality better, and it really helps you out 6 months later when you, or somebody else, is trying to figure out what that code does or why it was done that way.