Why well written commit messages can be of greater importance than you might think
I often come across commits in repositories that don’t make any sense or are way too generic in my opinion. Here’s my point of view on why I think we should spend a little bit more time making them clearer and self-explanatory. I’ll discuss two matters where I feel that better-written commit messages can make a difference to both developers and reviewers.
Commit messages as part of the documentation
Over the years repo’s will evolve, developers will come and go and business decisions will change. For me, one of the better ways to document your repository besides the code itself and the readme (while writing a good readme is a different story) is the commit log. This can be a steady base for most of the decisions made.
For example, I needed to look at a specific line of code as I wanted to know the context and reasoning behind it. Was it a business rule? A conscious decision? Or did we just implement it this way without reason? So I opened up the file in GitHub and looked at the blame log.
Can we think of something else then git blame as I’m really not interested in the who but on the why. Let’s try be more blameless in this world.
Then I saw the fantastic one-line commit saying fixed some stuff. That didn’t help me at all. I had to dig deeper into the code. Looked at some commits from the same timespan, asked some colleagues, and searched in Jira to find a potential story. It took me a while, but I found the answer to the question I was looking for in an old story. A simple commit message here with a reference to the story would have saved me a lot of time and it wouldn’t have cost the developer committing any extra time doing so.
I know we developers have a love-hate thing with documenting, but this is one of the easiest and non-time-consuming ways. There’s no reason to not give your pull requests a clear and self-explaining title.
Commit messages as part of peer-reviewing
Peer reviews are not only about authoring and improving code, they can also help in giving insights into the thinking process of the author. I sometimes see developers changing a lot of files and adding them to one big commit and then handing over the pull request to another developer. For me, this could be a signal that the developer isn’t working in a structured way which could reflect in the code quality.
Especially when you are a starting developer, the whole thinking process of solving a problem and coming to a solution is very important. If you can reflect the choices (good and bad) you made in small commits and change the code step by step it can make the whole process for the more experienced reviewer more understandable. He or she can deliver tailored feedback and coach and guide them on the path of becoming better developers.
For the reviewer, sometimes it’s also much clearer to walk through the commits and review those instead of going to all the files changed. That tab in Github can be overwhelming if a lot of files have been touched.
A nicely structured pull request can also be used as a checklist. Like, does your change reflect the story correctly and does it comply with the acceptance criteria and/or definition of done.
How to write a good commit message
What is a good message? For me, the first commit (which usually is also automatically the title of the pull request) should contain a story number reference, the title of the story or a small summary of the changes done. I can easily look up the TPP-219 story (in our case in Jira) to see what it was all about.
Another great way if you don’t define stories, is the Angular commit format. With the different types, you can make it clear what kind of commit you made. Possible types are chore, feat, fix, bug, etc which to me are very self-explanatory. Combine that with a summary and it should be very clear.
For all the following commits, just describe shortly what has been done in the commit and try to keep the commits as small and clear as possible. Look at the ones below, it’s a nicely structured flow that gives an insight into the process of reaching the solution.
Try to keep the messages in a professional matter. Don’t fancy up the commits too much. There’s nothing wrong with using some kind of humour or emoticons, but don’t overdo it. The essence here is that other people can easily understand what was done.
I hope that you will just spend that little bit of extra time giving your commit messages the TLC it deserves. It’s not only for the future U also for all the developers that will work on your projects. May the commit log Gods be forever in their favour!
Pro tip: squash & merge
If you don’t have it set already, try to allow only squash merging in your repositories. This will combine all the commits of your pull request into a single commit into the master branch. This will remove all the clutter from the commits logs and makes them much more readable.
Thank you for taking the time to read this story! If you enjoyed reading this story, clap for me by clicking the 👏🏻 below so other people will see this here on Medium
I work at Wehkamp.nl one of the biggest e-commerce companies of 🇳🇱
We do have a Tech blog, check it out and subscribe if you want to read more stories like this one. Or look at our job offers if you are looking for a great job!
