Commit Messages Should Say Why, Not What

When My AI Hammer Hit the Wrong Nail

The ChatGPT integration seemed brilliant when I first wired it into Gitonium’s commit flow in early 2023. Automatic commit messages. Like finding cheat codes for developer productivity: no more paralysis facing that blinking cursor, no more “Fixed typo” cop-outs. My new AI companion would clinically dissect each diff - “Increase login button padding from 5pt to 10pt (ViewController.swift)” - and I’d commit with the smug assurance of someone who’d “solved” productivity.

But pretty soon, something didn’t feel right. My shiny AI companion’s notes felt shallow. Accurate? Sure. Helpful? Hardly.

The thrill wore off quickly. I found myself at first tweaking the commit messages and then rewriting them entirely. Eventually, I stopped using the feature altogether. Why? Because knowing “what” changed wasn’t enough; I needed to know “why.”

The Problem with “What”

Let’s face it: commit messages describing only the “what” rarely offer any value. I can clearly see from the diff that padding was increased from 5 to 10, but WHY was it done? It’s making the view look bad in some languages (hello, Germans!), and I want to know if I can just set it back to 5 or if we need to order new translations.

Aviv Ben-Yosef from Codelord.net put it best:

These mean nothing. You may as well supply no commit message. Why did you even bother to write it?

Then we have the developers who throw their hands up and just type something, anything! into the commit message field. We’ve all been there, groaning when navigating a git history filled with gems like “fixed”, “make it work!”, “minor changes,” or even “blargh.”

And it’s more common than you think. One Redditor, nelmo44, shared the pain:

One coworker commits everything with just ‘mods.’

Ouch.

Why “Why” Matters

Code evolves rapidly in software development, but the intent behind decisions is timeless. Clear commit messages give context, reasoning, and crucial details for future debugging and refactoring. They’re breadcrumbs for your future self, guiding you back through the maze you built months or years ago.

Contrast “Updated padding from 5 to 10” with “Increased padding to improve touch accuracy on smaller screens.” Now, that’s something you can work with.

As Dgant from Hacker News reflected:

Commit messages might be pointless. Bad commit messages certainly are. I do a fair amount of git blaming on my own code and I find that my years-old messages do help me understand the purpose of old code.

Why Good Messages Mean Better Teams

Clear, intention-driven commit messages don’t just benefit individuals; they improve team communication and collaboration immensely. We always insist code should be readable for humans, not just machines. Yet we forget this principle when it comes to commit messages.

Ever spent hours tracing a bug through commit logs and blame, only to find unhelpful notes like “updated class”? Yeah, me too. Or perhaps you’ve worked in teams where every commit must have a Jira ticket number? A great idea in theory, right? Until a developer with writer’s block decides to put ONLY the ticket number. Or until you click the ticket and find: “Change padding from 5 to 10” – the same shallow “what” in a different container. Zero intent, zero context. It turns out that ticket authors can be lazy, too.

Meaningful commit messages become indispensable when debugging or refactoring old code from long-lost colleagues, regardless of what other systems you use.

As Stephen Whitmore from DEV Community puts it:

I see lots of commit messages that are like “Added x” or “Removed y”. It drives me nuts because I have to investigate further. Messages that give the reasoning behind the change saves time.

Writing Better Commit Messages: A Quick Guide

Want practical steps to improve your commit messages? It’s simpler than you think. Before hitting commit, quickly answer these three questions:

• Why was this change necessary?
• What issue does it resolve or address?
• What do future developers need to understand about this change?

Think of it as “Why Before What.” A simple mental checklist that ensures your commit messages remain meaningful.

Looking Ahead: Leave Yourself Better Clues

Looking back, my journey from AI-driven excitement to a deeper appreciation for clear, human-centered communication taught me a valuable lesson. Technology can simplify many things, but human clarity and intention remain irreplaceable.

Commit messages aren’t just chores. They’re opportunities to document your thought process clearly. They’re “our aid in times of great need,” as Aviv Ben-Yosef wisely notes.

So next time you’re about to type “fixed stuff,” pause and tell future-you why it matters. Six months from now, when you’re knee-deep in a critical hotfix at 10 PM, you’ll finally understand: commit messages aren’t documentation. They’re love letters to your future self.