If you write commit messages, take a couple of minutes to consider the following questions:
- Who reads your commit messages?
- When do they read them?
- Why do they read them?
Your answers likely depend on the kind of projects you’re working on. For my
personal projects, the answers to the first two are “only me” and “never”. As
a result, my commit messages are mostly one-liners along the lines of fix everything. That’s fine, because my projects are one-man short-term
operations.
At work, the situation is different. We have around twenty persons working on a codebase with over 150k lines of code and years of history. I can’t tell when (or if ever), my co-workers read my commit messages, but I do know when I read theirs.
The first time I read the messages is when the code is in review. I like to get quick overview of the changes by looking at the commit messages of the change request. However, it’s not a big deal if the messages don’t tell much - the main concern is the code itself.
The second time is more important: it’s when I try to understand the purpose of some old code. This often takes me digging through all the commits that have touched the code. Ideally the code would be self-documenting and there would be an explanatory comment next to it. In practice, the code and the comments get obsolete and out-of-sync. The code might be written or modified by a person who does not fully understand it. A wide-ranging change can miss something. Something obvious to the original author might not be obvious two years later. Sometimes you just need to make an awful hack.
In these cases the original commits introducing the code often helps me understand what is happening. It’s even better when there’s a commit message documenting the thinking behind the change: What problem does this commit solve? Why was it solved this way? Why wasn’t some other way used?
I’ve worked at ZenRobotics for only eight months, so my code hasn’t yet had to take the test of time. Nevertheless I’ve started to make it more future-proof by writing more extensive commit messages. Hopefully in two years I’ll be thanking myself for doing it.
I hope these questions help you figure out what kind of commit messages are useful for you and your contributors.
Further reading
- Tim Pope has recommendations for formatting the commits.
- John Graham-Cumming explains how his commit messages have become more verbose.