Writing Git commit messages
In a previous article I wrote about my Git branching strategy for small teams. In this one, I will look at the topic of writing commit messages. This is also a highly opinionated take, just like the previous article.
Writing a commit message
Every commit should have one main theme - one main purpose for why the change was made.
This should be made clear by the first sentence in the commit message.
The first sentence should be separated from the rest of the message with an empty line.
The body of the commit message should be written in point form, denoted by a dash at the first of the line. (Remember that the purpose of the message is for sending a clear message, not for writing essays.)
Each point should be written as a full sentence, properly punctuated. Why? The purpose of punctuation rules is to facilitate clear written communication. What’s the use of having (punctuation) rules if nobody follows them?
A useful tip to remember is that the project lead should understand from the commit message what changes are included in the commit without having to look at the code. The code should only be looked at if the lead wants to review the correctness of the code, not for trying to understand the purpose and scope of the commit.
Example
Here is an example of the type of commit message that I think is good:
Added the user avatar next to the comment.
- Modified the user API payload to return the avatar URL.
Since the commit message is supposed to describe what was done, it should be written in the past tense.
For consistency, my preference is to have the message written in the active voice. Below is an example of the same message written in the passive voice.
User avatar added.
- User API payload modified to return the avatar URL.
I’m being pedantic here really. This is just a preference for consistency more than anything else.
What not to write
What is a definite no-no is to write something along the lines of
made code changes
No sh*t genius!
This is just pure laziness and it makes my blood boil. 😠 A one-liner stating the obvious wastes the reviewer’s time and makes history traversal that much more difficult in the future.
Leaving the commit message empty is just as bad. It reflects the lack of care on the part of the programmer to think for the team or anyone else who will take over the code. (The grammar police in me is also triggered by the lack of a full-stop/period at the end of the sentence and the lowercase letter at the start.)
The other extreme - an extremely wordy write-up describing the commits - is also to be avoided. An overly detailed write-up defeats the purpose of the commit message, which is to summarise the key changes made in the commit.
If the reviewer wants more details, he/she should read the actual code changes.
Although this is to be avoided, it doesn't trigger me as much as an empty/redundant message because at least it shows that the programmer owns the work and puts in effort (albeit in the wrong direction).
Conclusion
As mentioned, this is my highly opinionated take on the approach to writing commit messages. In the next article in the series, I’ll share a few useful, but not frequently used, Git commands.