There are some things in the world of development that you appreciate much more when you do a lot of code reviews. One of those things is commit messages.
At first glance, commit messages seem to be a small, relatively innocuous thing for a developer. When you commit code, you type in some description about your code changes and then, typically, push your code somewhere for review by someone.
Regardless of whether the code you pushed is going to an open source project, an internal proprietary code repository, or just some code exchanged between friends working on a joint project, that simple little commit message tells the person reading your code a whole lot about you. It speaks volumes about the way you feel about the code you submit and the quality of the review you expect for your code.
As an example, suppose I was working on some code that fixed a bug. I got my code ready for initial review and I did the following:
$> git commit -a -m "Fixes some stuff"
And then I push my commit somewhere using git push …
Inevitably, what happens is that another developer will get some email or notification that I have pushed code up to some repository. It is likely that this notification will look something like this:
Change subject: Fixes some stuff ...................................................................... Fixes some stuff Change-Id: I79bbac32b5c99742b5cb283c6e55e6204bf92adc --- M path/to/some/changed/file 1 file changed, 1 insertion(+), 1 deletion(-)
And in the notification will be some link to a place to go do a code review.
Now, what do you think is the first thought that goes through the reviewer’s mind? My guess would be: Really? Fixes what stuff? By not including any context about what the patch is attempting to solve, you leave the reviewer with a bad taste in their mouth. And a bad taste in the reviewer’s mouth generally means one thing: a reluctance to review your patch.
OK, so what could we do to make the commit message better, to provide the reviewer with more initial context about your patch? Well, the first thing that comes to mind is to reference a specific bug that you are fixing with this patch.
Alright, so we amend our commit message to include a bug identifier:
$> git commit --amend -m "Fixes Bug 123456"
And subsequently push our amended commit message. The reviewer now gets a new notification that you’ve amended a previous patch. Now the notification includes the bug identifier. What do you think the next thought a typical reviewer might have? My guess is this: What, does this developer think that I’ve memorized all the bug IDs for all open bugs? How should I know what Bug 123456 is about? And here comes that bad taste in the mouth again.
OK, so this time, we will forgo the use of the time-saving -m switch to git commit and actually type a proper, multi-line commit message in our editor of choice that describes the bug that our patch fixes, including a brief description of how we fixed the bug:
git commit --amend # This will open up your editor...
Now we’d enter a good commit message … something like this would work:
Fixes Bug 123456 - ImportError raised improperly in Storage Driver Due to a circular dependency, an ImportError was improperly being thrown when the storage driver was set to XYZ. Rearranged code to remove circular dependency.
The commit message now will give the reviewer everything they need in the notification to understand what the patch is for and how you solved a bug, without needing to go to their bug tracker to figure out what the bug was about.
A detailed commit message shows you care about the time that reviewers spend on your patch and that you value the code you are submitting.