Spending time writing commit messages is an area of software development that's often overlooked. I used to do it myself—paid no attention to my commit messages and focused solely on the code. Although the code remains the most important part, paying attention to your commit messages will pay off.
Why it matters?
My perspective on the topic changed after facing difficulties understanding code written years ago, sometimes even code I wrote. When you work on a project that has been running for several of years, you often find yourself trying to change code that no one remembers the reasoning behind it. You end up on your own trying to figure it out or, in extreme circumstances, you end up circumventing it to reduce the risk of breaking production.
After being stuck too many times, I learned to care about my commit messages. However, once I made it a habit, I realised there were a number of additional benefits:
- Writing forces a deeper understanding of the changes. You understand the solution in your head, but there tend to be gaps in your thoughts that become clear when you explain it. You'll be surprised how many times you can find flaws in your solution. In my experience, this has been the greatest benefit.
- It can help you break down commits. If you start writing your reasoning behind the solution, and end up with a very long message touching on multiple topics, it's often a symptom your changes are doing too much and could benefit from splitting into multiple commits.
- It helps your code reviewers by providing context upfront. They can start by reading your reasoning before diving into the diff, likely answering many questions they would've had if they looked at the diff alone.
- It speeds up your team in the long term. You might think that spending time on this will slow you down—and it will on a given commit. However, it should lead to better solutions, smaller commits, likely fewer bugs and ultimately save time the next time the code needs to change.
Capture the why
I hope you find the argument as compelling as I do. The next step is to work out what you should include in the message to make it useful. And as I alluded to in the benefits, the key piece of information is the thinking behind your solution—the why.
Providing details of the thought process that made you pick that solution should be the goal of the message. Unfortunately, it's more difficult than it sounds. It's much easier to explain what the change does as it's explicit in the code, so that's what we naturally tend to do.
The why is in the thoughts you had when:
- You were coming up with the solution
- You realised it wasn't the right one and went for an alternative
- You discussed it with colleagues
- You found advice on the internet
All of this information seems obvious to you when the changes are ready to commit. You're done with all the thinking and already want to move on to the next thing. But this is the moment when you need to pause and record all this useful information.
Writing tips
The last point to master the skill is to think about how to write your message. This is something I still struggle with, and I thought to mention a few tips:
- Try to be concise. Keep the what in the title and focus the body on the why. It'll help you land the message.
- Think of your audience. If you're making changes in an area where the maintainers are not experts but depend on it, take the time to educate them.
- 1-liners might still require an explanation. The amount of code is not the determining factor, but rather the amount of thinking required to make the change.
I'm a strong advocate for investing time to provide quality in the work you produce. That covers the whole software development cycle, which starts to materialise in your commits. Writing great commit messages can be tedious at times—but it's a habit that pays off. It improves your thinking, helps your team, and strengthens your codebase. The next time you're about to commit, take a moment. Invest in the why.
Top comments (0)