Musings

Version control: Make your commit messages useful!

Regardless of which version control system you use, if you are working with other collaborators on a project (or even just to keep track of your own thought process over time), you will end up writing a commit message every time you make a change to your code. Don’t make light work of this commit message, it is a bigger entity than you or I, and without it we are all doomed…

All too often, I see (and have probably been guilty of this myself) people adding changes and simply writing what they did in the commit message. We see things like
“Added PotionService”
“Added Dumbledore house implementation”
“Added new interface” *cringe*

In the nicest way possible, such commit messages are useless. OK, that wasn’t nice. My apologies.

Seriously though, your team members could simply diff between your commit and the previous one and in an instant get all of the above information and more, so what’s the point in you using your energy to type it?

Instead, (as tempting as it is to do otherwise), you should write WHY you made the changes you did, rather than WHAT you changed. Explain the context of your change to the other collaborators in your project, so that they understand the need for it. They can’t read your mind, and won’t always know the business decision that drove the change. I read somewhere recently (I forget where right now, might’ve been a tweet, I’ll get back to you) that said something along the lines of “Each time you commit, write a message as if you’re going on holiday for a month and won’t be around to answer questions about it.”, and that’s exactly it. Put detail and context into these messages so you don’t get bothered with questions in the future as you’re going about your day writing more code (because what’s more annoying than someone distracting you in the middle of a deep thought process??).

Even when working on your own projects, writing a good commit message is hugely useful because we’re human, and we forget things. I can’t even remember what I had for dinner last Tuesday, so why would I presume I’d understand what I was thinking when I wrote this line of code 4 months ago? Now if only there was a way I could have documented that somehow… 🙂

For example,
“To honour the memory of Albus Dumbledore, a new house was created in Hogwarts and named after him. This needs to be reflected in our code.”
is miles better than a simple
“Added new house implementation for Dumbledore”

Don’t go overboard though. Writing a biography of Albus Dumbledore in your commit message is *probably* overkill (though you’d likely do a better job than Rita Skeeter did in her attempt).

Advertisements

One thought on “Version control: Make your commit messages useful!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s