Blogmark

Writing good commit messages has always been broadly undervalued.

I worked with a lot of very talented, experienced software engineers when I was at Hashrocket. There was a shared, cohesive engineering culture there that taught me a lot about being a good software engineer at an influential time in my career. I learned a lot of big and small practices that have made me good at this job.

One of the seemingly small ones was writing good commit messages. Commit messages that tell both what and why. Commit messages that respect you and anyone that comes after you that may one day be digging through the git history trying to figure out some "wtf is this line of code doing?" Commit messages that gave you a chance to explain yourself and "think out loud".

Good commit messages are an artifact and an asset. Low-effort commit messages are at best useless and at worst a misleading liability.

I think people write low-effort commit messages for a reason. They have other more pressing things to do and spending a little extra effort writing something that no one is going to read isn't worth it.

The fact that no one reading useless commit messages is a self-fulfilling prophecy. Combing through a git log, learning how to use the git pickaxe or git bisect, and digging into other tooling built on git all seems a bit pointless when the commits that get surfaced read as "fix bug", "please work", and "wip". You don't learn the tools. You don't look at commit messages. Now it's time to write a commit message, why bother typing more than "fixed stuff" -- no one is going to look at it anyway.

It is a magical moment when I've spent a good chunk of my afternoon hunting down a gnarly bug to then find a commit from two years ago (that I wrote, but don't remember writing, because it was two years ago) that explains the thing I'm wondering about. "Oh, this constraint is actually important and removing it violated an assumption we baked into the system."

I've inherited codebases with the exact opposite experience. I dig and dig, trying to figure out why only to find several 2000-line commits that might be related but the commit message has no details and the relevant parts are mixed in with hundreds of lines of other changes.

Interestingly, as coding agents completely change how we work, they perhaps benefit even more than we do from good commit messages. They are both fast and proficient at browsing git logs and narrowing down commits with the git pickaxe. Good commit messages give agents big contextual boosts.

Regardless of whether commit messages contain anything useful, you and I will figure it out. That's part of the job. Coding agents will figure it out too. Again, it's a small thing, so what's the bother?

The bigger thing at play here is that writing good commit messages taught me an attention to detail that has leveled me up, made me a better software engineer, and helped me stand out in a crowded field.