Some developers have a habit of committing their code without a clear commit message.
I was one of them! Now, I consider that to be a bad habit.
With time I realized that it is hard to remember the intention of an old commit by just looking at the code. It becomes even impossible when reviewing a colleagues’ code.
In this post, I will be sharing a template message I adopted with one of my previous teams.
Below is the template. As you can see, it is split into four colors. In the next part of the blog, I will break down the message to explain each of its sections separately.
[Issue Tracker #] One-line summary of the commit description Why is this change necessary? - Detailed description 1 - Detailed description 2 ...
Section I – ‘[Issue Tracker #]’:
Between the two brackets, I write the issue number corresponding to this commit. The format here varies depending on which issue tracking system I am using (ex: [ProjectName-123] for Jira and [#123] for Github.)
Message so far
[#5] One-line summary of the commit description Why is this change necessary? - Detailed description 1 - Detailed description 2 ...
Section II – ‘One-line summary of the commit description’:
In the second section, I try to summarize the full commit in just one sentence. Failing to do so means that my commit is doing more than one task and needs to be broken down.
Message so far
[#5] Move the constants out of the GildedRose class Why is this change necessary? - Detailed description 1 - Detailed description 2 ...
Section III – ‘Why is this change necessary’:
In this line, I try to answer the question ‘Why is this change necessary?’ In most cases, this line is a copy of the ‘Issue Title’.
Message so far
[#5] Move the constants out of the GildedRose class In order to, refactor and clean the code of GildedRose - Detailed description 1 - Detailed description 2 ...
Section IV – ‘Detailed Description’:
Finally, I replace the items of the list in this section with a detailed description of the important technical changes I did in the code. Here I try to think of what I should remember if I was to read this message a couple of months ahead.
The final commit message looks like
[#5] Move the constants out of the GildedRose class In order to, refactor and clean the code of GildedRose - Make MAX_QUALITY, MIN_QUALITY & MIN_SELL_IN_DATE as local variables ItemVisitor - Move AGED_BRIE string to the AgedBrie class - Move SULFURAS string to the Sulfuras class - Move CONCERT string to the Concert class - Adapt the tests accordingly
By just reading this last message, anyone should deduce that firstly, in this commit I only moved some constants from the GildedRose class. And secondly, the commit was part of a larger code refactoring of the GildedRose class.
How is this helpful?
So, why do I consider this to be helpful?
Here are my reasons:
- Forces me to code in baby steps and thus have small commits.
- By having small commits, it would be easier, later on, to track down bugs.
- Makes code review easier and faster
- Most SCMs and tracking tools are now integrated, that makes linking commits to an issue seamless. This link has 2 benefits:
- By just adding the ‘Issue Number‘ in the message, I can refer to the issue’s details to view all the corresponding commits.
- Limits my development to only the features and bugs in the project’s backlog. I won’t be submitting any useless code.
- Serves as a documentation for my code. More than once, I referred to those messages when writing a detailed technical report of our product.
At first, it was a bit annoying to write this message for each commit. But as we realized its benefits, it became a habit for us!
You don’t have to adopt this exact message, you can come up with any format you think is good for you as long as it is clear and concise.
Enjoy coding 🙂