Good commit messages are the unicorn of the person maintaining legacy code. I will try to review some commit messages I’ve found over the years with its pros and cons.
I’ll break this into two categories: solving bugs and adding features.
Solving bug commit messages
The brief
Fixing code
Pros: At least it is not destroying code Cons: What the hell is happening there? I can commit anything under that excuse
More specific brief
Fixing bug
Pros: At least it is not introducing bug. Cons: What the hell is happening there?
Making it work again
Pros: It is working… again Cons: Why wasn’t it working before?
Fix bug in module X
Pros: Module X has one less bug Cons: At least I have a bit more context. Too bad I could deduct that information from the diff.
Fix #23344
Pros: I have a ton more context of the reason behind the error. Unfortunately I don’t have it immediately. If I use a modern issue tracking system I can navigate to a discussion regarding this bug from my browser or editor. Cons: I have to go to my issue tracking system
Fix #23344 Removing n+1 problem
The problem was that these lines were causing a nasty n+1 problem because we have a lot of entries in our “users” table.
Pros: I immediately have all the context of why the change was made and what the guy that had written this piece of code thought he was doing. Cons: A bit verbose sometimes
Adding feature commit messages
test / testing / just testing
Pros: The code is probably tested Cons: Everything else
Renaming method
Pros: Probably the new name is better Cons: I saw it in the diff already. Why it is a better name?
Refactor
Pros: No behaviour was changed. Cons: Just kidding. Please, tell me why you needed to refactor this.
Applying observer pattern
Pros: You know at least one design pattern. Cons: Why is that a good idea in that scenario?
Added new stories notification
This feature was requested in #112233
We are adding two new methods in the API so we can integrate in the future easier in our mobile app. These methods are now used in the frontend only.
Pros: A lot. Cons: Verbose
Putting it all together
When I look into a commit message, often, I am desperately looking for the reason why the change was made. I don’t want to know what changed. There is a diffing tool for that. It does not hurt if it is briefly describe what is done in the commit message but the most important part is why the change was made. When I read a commit message it often means that I am investigating a problem in the code so I need to know your assumptions to see if you were wrong or the assumption is now not valid.
Have some empathy with a person investigating something wrong with your work, most probably, your future self.
With the diff I can already see what changes were made. The text just explains what the hell I was trying to do and more importantly why. This gives the investigator a great deal of information to know if I was wrong in case something needs to be fixed.
This is one of the reasons I am starting to avoid using the -m switch of git commit
git commit -m “I did something with the code”
If we commit like that we are encouraging small commit messages and it becomes too tempting not to explain a little bit to the next programmer.
That is, also, why these days I’m embracing the idea of interactive rebasing my branches before merging to the main branch. This gives me some introspection time to organize the commits appropriately and reword some commit messages to make the lives of future readers better.
Now probably a ton of people will come with better ideas than this for commit messages. New ideas are welcome.