These days every developer is using some form of version control to manage their code bases and contributions from their team. Most predominantly we are using GIT as our version control of choice.
No matter what form of version control you are using, the most important part of keeping a usable code history is, “Writing a proper commit message.”
Why?
If you have ever used git log --grep or used an IDE to find commits you know the importance of having a relevant message to locate the correct commit without having to look at the changes done on each one individually. For that I argue, the most important reason to write a proper commit message is search ability.
Another good reason is, proper messages automatically document the evolution of your code over time. New developers, or even yourself years later, can see when and why something was added to the code base.
Lastly, it will make whoever is in charge of your project much happier. Trust me, you can make your senior engineer’s day by providing proper messages.
How?
All commit messages should always contain three things:
- A ticket, task, or conversation number.
- An explanatory subject line.
- Verbose body.
A ticket, task, or conversation number
The most common naming convention for adding a number to a commit is [#<number>]. There are a few other conventions used so you’ll want decide on a common one to use for your team or use the convention your project management integration uses.
Chances are, you are using some form of project management tool. Your tool generates a unique ID for any individual task. Adding the task number to a commit message makes it simple to find all the commits which are done as part of a task. Most project management systems also provide integrations to automatically link commits to tasks simply by using their convention within commit messages.
If you are using GitHub or something similar you can automatically link commits to issues or pull requests by adding the issue number to commit messages. You can also automatically close issues with special keywords. More info here.
An explanatory subject line
This is your chance to highlight what you worked on. It should be short, precise, and include the name of the feature or area you were working on. This is where you include the ticket number. The maximum readable length is 72 characters, so don’t over do it with descriptive words or proper grammar.
Some examples of good subject lines:
- [#4548] Updated the footer logo to 4k version
- [#123453534332] Fixed JS bug on Safari with resize timeouts
Some examples of bad subject lines:
- Address pull request’s comments.
- SAVE POINT
- Restore grey background
Verbose body
This part of a commit message is often neglected by junior developers. I can’t stress enough how important a good body is to understanding the evolution of a code base. I understand, you finished your code and are excited to commit and share it, but please spend a few minutes on the body before you do.
This is your chance to write notes about what you did and why while it is still fresh. Explain in detail what is contained in the commit. Document any hard to understand things you did. Think of this as complimentary to the docs written in your code. If you wrote some really great descriptions for a method, copy/paste that description into the body.
It should be a minimum of 1 paragraph but can be several paragraphs long. Personally, 2-4 paragraphs seems to work the best. Lines should be no more than 72 characters, so use line breaks to wrap lines. A blank line should always been included between the subject and body.
Some examples of a good commit body:
We noticed on retina devices the logo in the footer looked pretty grainy.
This was fixed by including 2 logos and using media queries to switch
between them based on screen pixel density.
We added a 4k version in the same location as the 2k version.
Safari has limitations withsettimeoutwhich runs before all resources
have loaded. This could be seen in the browser console. The header
would not resize because the timer was skipped.
Awindow.loadedevent was added to assure the resources were loaded
before this fires.
Some examples of a bad commit body:
(blank)
I tested everything and it should work better now.
I worked late so I’m tired.
Putting it all together
While you’ll put your own voice on your messages, following the above principles will certainly make your commit messages effective.
PRO TIP: I’m in charge of hiring for my team. When I audit a new candidate’s work, if I see commit messages written as suggested, I immediately move them to the front of the line.
This is what our example look like all put together:
[#4548] Updated the footer logo to 4k version
We noticed on retina devices the logo in the footer looked pretty grainy.
This was fixed by including 2 logos and using media queries to switch
between them based on screen pixel density.
We added a 4k version in the same location as the 2k version.
[#123453534332] Fixed JS bug on Safari with resize timeouts
Safari has limitations withsettimeoutwhich runs before all resources
have loaded. This could be seen in the browser console. The header
would not resize because the timer was skipped.
Awindow.loadedevent was added to assure the resources were loaded
before this fires.