The Sacred Art of Clean Commit Messages
We’ve all been there. It’s late at night, you’re racing to finish a feature, and you scribble a quick “fix bug” or “oops” as a commit message. No big deal, right?
Wrong. Good commit messages make you stand out as a developer and they are always something you should take the time to craft. Here’s why they matter - and how to improve them.
Why Commit Messages Matter
A commit message isn’t just documentation - it’s a chance to communicate your code’s intentions. Developers, even long after your departure, closely review commit histories to understand the decisions that went into the code. Descriptive commit messages are a nod to both yourself and those who come after you.
To illustrate this…
Bad commit messages lack context:
Good commit messages provide clarity:
Fix null pointer exception in parser by handling empty inputs
Beyond working efficiently, writing solid commit messages also displays communication skills. Communication is a key differentiator in our development careers. Those of us who master this skill (in all facets) will find ourselves highly regarded and welcome among the cross-functional teams we work with.
Committing to Better Commit Messages
One “hack” I use is to rely on the standards defined in semantic commit messages - these clearly explain the why and how of each change. Here are some common conventions:
- fix: bug fix (explain the bug)
- feat: new feature (explain the feature)
- docs: documentation update
- style: formatting, missing semi-colons
- refactor: improving code without changing functionality
- test: tests added, updated, or fixed
I know, writing semantic commit messages takes more time and energy than dashing off a quick note. But it’s worth developing the habit. Here are some excuses for skipping commit message best practices - and why they don’t hold up:
- “I don’t have time!” - Take a little more time now to save everyone time later figuring out messy commit histories.
- “I’ll go back and clean them up later.” - You’ll never go back. Just get in the practice now and it will become second nature!
- “No one reads these things anyway.” - You might be surprised! And it still looks sloppy to ignore best practices.
- Commit messages explain and document your code and the decisions that influenced it - take time to write meaningful ones.
- Semantic commit messages are an easy way to clean up your commits.
- Good commit hygiene displays positive traits like care for team members and communication skills.
Personally, I’m committed to improving my commit messages. I feel awkward when I need to quickly commit something. So, whether working on personal projects or professional teams, aim to write commit messages you’d be proud to show off!