Writing great commit messages for better code review

Do you work with others writing code? The chances are, you use some form of version control.

Getting the best out of our versioning system can sometimes not be the most natural thing to do.

Very often, our default behaviour when committing code is to commit frequently and use short messages that (might) describe the change.

This may work for you when you’re coding solo but in a team it can make understanding our code harder.

Imagine this scenario (it’s actually a real one)…

A developer on your team adds a new feature. There’s a string of commit messages that look like…

132rafa9 Add form
78aae001 Change button to blue
e1189daa Fix submit bug

Then they ask for review.

Great, we’re a team and we believe that reviewing our code helps code quality and spread understanding throughout the team.

There’s a problem though. The commit(s) make it hard to read both the intention of this change and understand how the code ended up looking like this.

Code review becomes a chore for the reviewer and the person seeking review. Rather than spend time discussing the merits of the code itself, we can end up discussing alternative ways that have already been considered by the author. Or perhaps get into a multi-comment exchange trying to get to the intention of a piece of code.

I believe there’s a better way. A way to give the reviewer more context to our changeset. And with more context comes better discussion about the code and less time wasted discussing the alternatives that may have been explored or why we have chosen a particular route.

Code review is not just about making the code better, it’s also an opportunity to learn something new. About the codebase itself or maybe a way of solving a problem that you hadn’t seen before.

Finally it’s a great opportunity for a team to buy-in to a change and commit to its ongoing maintenance in the system.

When you get to that place, you can work together as a team so much more efficiently and happily.

So how do we do it?

The first step is by writing great commit messages.

There are 2 parts to this. First, I find getting agreement about a standard format is a good first step in getting us to think more about our commit messages.

This post by Tim Pope is my usual reference point for teams.

That covers the how we format it and then the next question is what should be in it?

This is the part that takes a little extra thought but it is very worthwhile. A great commit message should communicate things that code can’t. It’s important that it covers the why of this changeset. Sometimes that can be why are we doing it, but most useful is answering the question “Why is this change the best one given the current constraints?”.

The constraints we work under too often go undocumented but are critical to shaping the solution we present in our commit. Without understanding them, how can anyone else intelligently review our code?

So, for me, the primary goal of a commit message is to answer that “why” question.

Let’s see an example…

| Author: Felix Clack <my@email.com>
| Date:   Mon Oct 2 14:19:16 2017 +1000
|
|     Store the user record and display an avatar

Here’s a classically terse commit message. I used -m which all but guarantees that I will write a commit message that isn’t helpful to anyone else.

It describes the what and not the why of this change.

Compare it to another commit from a different project I worked on…

| Author: Sam <sam@email.com>
| Date:   Tue Sep 19 16:29:51 2017 +1200
|
|     Implement deep linking to individual blog posts (#379)
|
|     For now the simplest approach is to include an 
|     activity type in the deep link. This allows us to translate 
|     headers in HomeDetail without the hassle. It’s very 
|     complicated to do this in any other way with react-navigation.
|
|     This will support deep links in the format: 
|     `yhi://app/home/activity/-KtjzD5o7OoYAuy6TjTH/blog`

Notice the detail here, the context around his choice of solution and even a hint of what we can communicate to non-developers on this project.

It’s a great message that led to a more informed discussion about the change.

Let your commit messages tell the story of why your code ended up like it did and your team will thank you for it. And you will thank yourself next time you run git blame to figure out why the code is there.