The black art of commit messages

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

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

Pros: At least it is not introducing bug.
Cons: What the hell is happening there?

Pros: It is working… again
Cons: Why wasn’t it working before?

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.

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

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

Pros: The code is probably tested
Cons: Everything else

Pros: Probably the new name is better
Cons: I saw it in the diff already. Why it is a better name?

Pros: No behaviour was changed.
Cons: Just kidding. Please, tell me why you needed to refactor this.

Pros: You know at least one design pattern.
Cons: Why is that a good idea in that scenario?

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

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.

Leave a Reply

Your email address will not be published. Required fields are marked *