AHMAD ATWI

A good commit message can make a difference!

—

by

Ahmad Atwi
in ,

Some developers have a habit of committing their code without an explicit 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 colleague’s code.

In this post, I will share a template message I adopted with one of my previous teams.

For simplicity, I will refer to one of my commits to a fork of the GildedRose-Refactoring-Kata on my GitHub account.

Message Template

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 #]’:

I write the issue number corresponding to this commit between the two brackets. 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 replaced the items in this section with a detailed description of the essential technical changes I made 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 I only moved some constants from the GildedRose class in this commit. And secondly, the commit was part of a more extensive code refactoring of the GildedRose class.

How is this helpful?

So, why do I consider this to be helpful?

Here are my reasons:

  1. Forces me to code in baby steps and thus have small commits.
  2. By having small commits, it would be easier, later on, to track down bugs.
  3. Makes code review more accessible and faster
  4. Most SCMs and tracking tools are now integrated, which makes linking commits to an issue seamless. This link has 2 benefits:
    1. By just adding the ‘Issue Number‘ in the message, I can refer to the issue’s details to view all the corresponding commits.
    2. Limits my development to only the features and bugs in the project’s backlog. I won’t be submitting any useless code.
  5. Serves as documentation for my code. More than once, I referred to those messages when writing a detailed technical report on our product.

Finally…

At first, writing this message for each commit was a bit annoying. 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 🙂

Comments

Leave a comment