Writing good commit messages is something I sometimes obsess over. To me, commits need clear messages that, when read, tell a story about how the project has been evolving. I get rather annoyed when a teammate commits things like “Implements X’s feedback”. This tells nothing about the commit, nor about the history of the project. Over the years I’ve found that a good rule of thumb is to describe what you did, not how. This is better explained with an example:
Say you are fixing a bug that requires you to change a multiplication operation for a sum operation. Instead of writing
“Changes multiplication to sum”
You could write
“Fix the total price calculation. Wrong totals were given.”
This way anybody reviewing the git log can see right away that in that particular commit a bug in total price calculation was fixed. The first message doesn’t tell a story about the project, it tells a story about the code. You don’t want that in your commit messages.
Another thing I’ve learned is that commit messages aren’t always about the thing you are trying to fix or implement. For example, I recently had a teammate report to me that an form error was not displaying in the right place. This was for a floating form that opened via a button. When the user didn’t enter information in a required field, the form would disappear and the error message would be displayed in the main page instead. This was confusing to say the least.
My job was to display the error message right there when the form was open. I saw that the form already implemented HTML validation for some of the required fields, so it was a good idea to do the same for the ones that it didn’t so the experience remains consistent. I did just that, and when the time came to write a commit message I was tempted to say something about the commit being for fixing an error display issue. But when I thought about it a bit more, I realized that was not what the commit was about. The commit was about adding HTML validation to fields that were missing it. So I wrote that instead:
Implement HTML validation for fields that don’t have it.
But I’m guessing future me may want to know “why” this was needed. So, I made future me a favor and added a longer explanation as well as the initial “heading” message above:
“We want to show errors about missing information for X and Y input types when they are required right on the form instead of having the form refresh the page with an error message.”
I’ve found that sometimes it is useful to explain why you did what you did as part of the commit message, but I’m always careful to put that in a paragraph bellow the commit heading which explains in short words what I did. I don’t always add a commit message body explaining why I did what I did. I usually only add a commit message heading that explains what I did in as few words as I can, but whenever I find it necessary, I add a commit message body without worrying about commit message length.