When “Fixed Stuff” Wasn’t Enough
In my early Git days, I used commit messages like Post-it notes: short, vague, and disposable. “WIP”, “fix bug”, “update code” — they made sense in the moment, but they didn’t hold up over time. Looking back at the history a few weeks later, I couldn’t tell what anything meant. Worse, no one else could either.
I didn’t realize it yet, but I was sabotaging myself. My commit log had no story, no context, no intention. I was losing the chance to explain why changes happened, and that loss came back to haunt me during bug hunts, code reviews, and onboarding new teammates.
It wasn’t until I worked with a senior engineer who wrote messages like “Clarify error handling when network request fails” that I saw what was possible. His commits read like a changelog and a design doc. I was intrigued. Then I was inspired. Then I started writing better messages.
This post captures the shift: how I went from throwaway messages to thoughtful summaries. It changed how I worked, how others worked with me, and how we understood our history.
Commit Messages Are UX for Developers
A good commit message is more than syntax. It’s empathy. Someone will read that message. They’ll be trying to understand a change under pressure—maybe fixing a production issue at 3 AM. A good message guides them. A bad one frustrates them.
# Good
git commit -m "Fix overflow issue in mobile footer layout"
# Bad
git commit -m "fixes"
The first example tells you what changed and where. The second tells you nothing. Which one would you rather see when bisecting?
| Message Style | Immediate Clarity | Context | Useful in History |
|---|---|---|---|
| Specific + descriptive | High | Strong | Yes |
| Vague / generic | Low | Weak | No |
Once I started seeing commit messages as part of the developer experience, I changed how I wrote them. I asked myself: What problem does this solve? Who will read this, and what will they need?
It wasn’t about verbosity. It was about clarity.
My Commit Message Formula
After some trial and error, I started using a loose format that worked across teams and projects. It helped me stay consistent, even under time pressure.
My formula:
- Imperative voice (e.g. “Add”, “Fix”, “Update”, “Remove”)
- What changed, with enough context
- Why it matters, optionally in body
git commit -m "Add timeout to fetchUser call to avoid long hangs"
For larger commits, I used a multi-line message:
git commit
Add retry logic for booking API
The booking API occasionally returns 502s, especially during high traffic. This change adds exponential backoff and retry to improve stability.
| Component | Purpose |
|---|---|
| Title (short) | Summarizes the change in 50 characters |
| Body (optional) | Explains why the change exists |
| Footer (optional) | Reference issue ID or breaking change notes |
Even simple messages benefit from a bit of structure. It shows intention. It shows care.
Code Is a Conversation
Code doesn’t speak for itself. Not fully. The context behind a line of code—the why—is often in your head. Unless you write it down, it disappears. Commit messages are a lightweight way to preserve that insight.
They’re not for you now. They’re for future you. Or for the teammate you haven’t met yet. Or for the person debugging something critical long after you’ve left the project.
Good commit messages are one of the lowest-effort, highest-impact things you can do as a developer. They improve onboarding, reviews, reversions, and trust.
Start small. Don’t stress about being perfect. Just be a little clearer than you were yesterday. And remember: your history is a product, too.