How to write a commit message
"Add guideline to improve code maintainability"
Commit messages are as crucial to code maintainability as code. A codebase should have a commit style guide just as a code one. Your team, even better, all teams in your organization, should agree on a set of standards to write commit messages.
I suggest a guideline simple and flexible enough to be adopted by most of the projects. But first, it is important to justify why I think a single sentence is enough for a commit message.
It's all in your header
According to Linus Torvalds, a good commit message has a header, a body with several paragraphs and a footer with a signature. But it is unlikely that your project is also powering the internet and supercomputers, with thousands of developers writing code for it.
A typical project within a company benefits from the concision of a single-sentence commit message. Detailed explanations of what you are doing and, more importantly, why you are doing should go into the Pull Request description.
Just remind that keeping detailed descriptions in your PR only is a trade-off. The benefit is that you save some work, creating one encompassing description for several commits. The risk of doing that is that all that context information is locked to whatever tool you use for version control management, while the commit messages are kept by Git itself. This portability advantage might be essential for some projects, but most of times, your dependency on Github, Gitlab, or Bitbucket is already established by several other factors and the diligence to keep extensive commit messages it not worth the trouble.
The guideline
Write a concise message, starting with a capitalized verb in the root form, explaining what you did to the code and what the code does to the software“Write a concise message, starting with a capitalized verb in the root form, …”
The first part of the guideline is about style and formatting.
“Write a concise message ...”
I used to think commit messages should have a limit of characters. My current position is that the tools used to read commit messages have powerful enough customization options that the data itself does not need to be limited by hard rules.
Concision is your goal, but concision is about the ratio of valuable information by the number of words, not the absolute number of words alone. Still, writing commit messages with more than 80 characters should be the exception, no the rule. As Einstein used to say about his commit messages: as short as possible, but no shorter.
“...starting with a capitalized...”
Capitalized, so it's easy for a human to parse where the message starts.
“...verb...”
Starting with a verb is the most straight-forward structure to describe an action.
“... in the root form...”
The root form — the one used for imperative or simple future conjugations — is the shortest one, saving a few characters without losing information.
“…explaining what you did to the code and what the code does to the software”
The second part of the guideline is about the content of the message.
I prefer a standardized structure rather than being restricted by a set of pre-defined verbs and words. I like to use this somewhat more verbose structure that gives more context while keeping the information-per-word ratio high.
Intervention (verb + object) + Effect (“to” + verb + object)
“...explaining what you did to the code...”
The first verb and its object is the intervention. The change you are introducing into the code. How are you affecting the original code? You are editing style, upgrading package, refactoring file structure, rewriting methods, adding endpoints, etc.
“…and what the code does to the software”
The second verb and its object is the effect. The change in the software behavior that your change in the code creates. What is the consequence of your code changes?
Following the examples above, a complete commit message could be:
“Edit style to implement new button design”
“Upgrade package to remove vulnerabilities”
“Refactor file structure to improve code readability”
“Rewrite methods to improve performance”
“Add endpoints to implement new customer dashboard”
There are a few exceptions where you don’t need the complete structure. When fixing a bug, go straight to the effect part and explain what you are fixing. It benefits the reader to know from the beginning that this is a bug fix. Example: “Fix bug in admin role permissions”
When performing git actions, like merge and revert, keep it to just the intervention part. Examples: “Merge branch B into master”, “Revert Pull Request #302”.
“ ”
Also, no need to add a period in the end. As a commit message will always be a single sentence, it adds no information.
