Useful commit messages
While building a new feature or refactoring code, do you ever look at some piece of code and wonder what the intention of the writer was? I sure do. So, you annotate the code and check for the commit. Then you see a commit message like: ‘fixed bug’.
This doesn’t really help. What was the bug? How does this change fix it? This is not a useful commit message.
Other examples of bad commit messages I see more than I like are: ‘fixed review comments’, ‘work in progress’, ‘refactored’.
A commit message should be useful, so it can help the reader understand the change and act accordingly. So what defines a useful commit message?
There are a lot of conventions on writing commit messages. I will not go into detail on all of them here, because they have been covered in other articles in more extend. I want to focus on the commit message itself, because I think that is the most important part and I want to give it some more exposure.
The commit message should provide context to the change that was done. More specifically, it should say why this change was done. The reason someone(including yourself) looks at your commit message is probably because that person is confused or sceptical about the change you made in the code. That person wants to understand why the change was necessary.
Example
I was refactoring a service that worked with a filestore when I noticed that for every request to the filestore, a new Sardine client was created. This felt like a lot of overhead to me, so I checked the git log and the change was as following:
With the following commit message:
create new sardine client for every request
This commit message was not very helpful, because it doesn’t provide more information than the diff of the commit. We can see in the diff of the commit what the change was, but this commit message doesn’t tell us why. Why was the Sardine client substituted with a Builder that creates a new Sardine client for every request?
I was considering to refactor this code, but decided to check the Sardine documentation on their website first. There they recommended to use a new instance of the Sardine client every call, for thread safety.
If the reason for the change would have been added to the commit message, it would have saved me some time and confusion. With a commit message like the following it is clear to the reader why this change is necessary:
Create a Sardine client for every request Sardine documentation recommends creating a new client every request for thread safety.
Structure of the message
Put the what in the first line of the commit message (the subject line). Write it in a way so that it tells you what will happen if you apply this commit. This way when viewing the commit log, it is easy to see which commit applies what change to the codebase. After that, leave a blank line and then put the reason for the change in the body of the commit message. This is the part that gives context about the change and explains the reason the change was needed.
Structure of commit message:
Short summary of the change (what) Explanation why the change was needed. If necessary, also add why this particular solution was chosen.
Small commits
While building features or refactoring you are constantly making choices. Therefore I think commits/changes should be as small as possible. In the commit message, this allows you to give context on a choice you made while implementing a solution. You can also do this using comments in the code, but for comments it is not always clear to which part of the code it applies to. It may seem hard to make small commits while building a feature, but remember you can split up your change in multiple commits.
Obvious changes
Sometimes changes are obvious. Then the commit message does not require much thought. For example: If you are fixing some spelling mistakes, a commit message saying “Fix typo’s” is clear enough. It does not require further clarification.
Summarizing
Create small commits so it’s easier to describe the context in your commit message. Ask yourself the question every time you commit something: If somebody else sees this change and the commit message, will they understand why this change was done?
There are more conventions about commit message on the internet. For example about the length of the text of your commit message. You can look them up if you are interested.