A month ago I changed one habit and nothing else: every commit message I wrote had to read like a changelog entry. Not "fix bug" or "wip" or "updates". A sentence a stranger could understand, saying what changed and why.
I expected nothing. I got the easiest month of code reviews I have ever had, and a git history I can actually read. Here is what happened.

The rule

Three parts, all mandatory, all short:

  1. What changed, in plain words: "Fix login redirect loop when session expires"
  2. Why, in one clause: "because expired sessions sent users back to the login page forever instead of showing an error"
  3. No filler words. No "fix stuff", no "minor changes", no "asdf". If I could not write the why, I was not allowed to commit yet. That was the real rule hiding inside the rule: if you cannot say why you changed something, you do not understand the change well enough to ship it. ## Week one: annoying The first week was slow. I caught myself writing "update auth" out of habit, deleting it, and actually thinking about what I had done. Twice I found real problems this way: once I was about to commit a change whose why was "the test was failing", which is not a why, it is a symptom. Digging one layer deeper, I found I had been fixing the test instead of the bug. The commit message rule caught a mistake my code review probably would not have. My commits also got smaller. A changelog sentence does not fit a commit that does five unrelated things. "Fix login redirect and update styles and bump dependency" is not a changelog entry, it is a confession. So I started splitting commits. Smaller commits, clearer messages, and — this surprised me — fewer merge conflicts, because my changes were smaller and more focused. ## Week two: the review effect This is where it paid off. My reviewer — a friend who reviews my side-project code — left a comment I had never seen from him before: "Easy review, thanks." He approved a pull request with eleven commits in one sitting, where the same size PR used to take him two days and three rounds of questions. The reason is simple. A reviewer reads your commits before they read your code. Clear messages tell them what to look for in each diff. "Fix login redirect loop when session expires" tells the reviewer to check the redirect logic and the session handling, and nothing else. "Updates" tells them to read everything, carefully, suspiciously. The message is the map. A bad map makes the reviewer walk the whole forest. ## Week three: the history effect Three weeks in, I needed to find when a bug was introduced. Old me would have bisected blindly. New me ran git log --oneline and read the messages like a story: each line said what changed and why, in order. I found the suspect commit in two minutes, from the message alone, before reading a single diff. That is the part nobody tells you about commit messages. You write them for your reviewer today, but you read them yourself in six months, when you have forgotten everything. Future you is the most important reader of your git history, and future you has the memory of a goldfish. Write for them. ## Week four: it stuck By week four I stopped noticing the effort. The messages just came out that way. A few things that helped it stick:
  4. Write the message before the code. When I start a task, I write the commit message first, as a promise: "Add rate limiting to the login endpoint because brute-force attempts are hitting it." Then the code has to live up to the sentence. If the code drifts, the message tells me.
  5. One change, one commit. If the message needs the word "and", split the commit. Two commits with two clear messages beat one commit with a compound sentence.
  6. Read your own log every Friday. Five minutes, git log --oneline -20. If a message embarrasses you, that is the lesson. Fix the habit, not the history. ## The honest downside It costs about thirty seconds per commit, and it costs honesty: you cannot hide a sloppy change behind a vague message anymore. Some days, when I am tired and just want the code in, those thirty seconds feel like a tax. They are not. They are the cheapest code review you will ever buy, from the person who knows the code best — you, five seconds after writing it. Try it for a week. Not forever, just a week. Write every commit like a stranger has to understand it from the message alone. Then open your log on Friday and read it like a story. If the story makes sense, keep the habit. If it does not, you will know exactly what to fix — because the messages will show you.