“’Fixing a bug’ is a great commit message!” said no one.
Why? Because commit messages like this make our jobs frustrating.
Good commit messages on the other hand, make our jobs easier and save everyone time as they:
- give more clarity to the diff author - if you, as the diff author, have a hard time writing a good commit message maybe your change is not ready for review?
- help understand what the person who wrote the code was thinking which makes it much easier to grasp reasons why the code was written the way it was written and helps avoid introducing regressions
- provide the context for code reviewers and as a result facilitate faster code reviews by lowering the barrier to entry for anyone willing to review the change
- allow finding commits quicker
Note that this is not about making commit messages longer. Long commit messages are not necessarily good commit messages. Good commit messages are short but informative. In many cases a single line explaining what the change is about is sufficient. More complex changes, especially bug fixes, often require more context:
- What exactly the change is about. This information is a must, and should be always included in the title.
- Why you are making this change. What scenario it unblocks. What issue it fixes.
- Short description of implementation details.
- If fixing a bug, how to reproduce it.
- How the change was tested - especially useful for any validation beyond unit tests
- Links to related issues or tasks
You can find an expanded version of this post here: https://growingdev.substack.com/p/how-to-remove-unnecessary-friction
💙 If you liked this article...
I publish a weekly newsletter for software engineers who want to grow their careers. I share mistakes I’ve made and lessons I’ve learned over the past 20 years as a software engineer.
Sign up here to get articles like this delivered to your inbox.
Top comments (5)
This! I'd also add that conventional commits might be useful to consider in case you'd like to generate changelogs and other things. Plus it makes for a more organized git history. We have checks set up for this on our repository for these two purposes.
Good point about changelogs. I remember it took me more time than I want to admit to prepare a release once because commit messages were not good enough to tell the story.
A good post on commits. I've seen some bad commits that are unprofessional. Sadly, here are a few I seen a few years ago:
" [insert person's real name] broke it"
"THAT WAS NOT UNUSED CODE"
Commits are not social media posts. Good commits makes things much easier.
This is very sad. Everyone makes mistakes and there is no need to put someone in the spotlight like this. (Also, this person could perhaps have prevented this by reviewing the diff that introduced the issue?)
I agree. Everyone makes mistakes and it's not right to drag someone through the mud in the commits for a mistake that can be fixed.
As to provide context. The person who made the unprofessional comments did not review the diff. This could have been prevented in PR and they could have made a comment to point out the mistake. After it is corrected, it can be approved and merged.
Very sad to see something like this happened. Another reason why commits and PRs should be done right.