Besides writing working code, programmers do many kinds of documentation.

  1. Code comments
  2. Commit messages
  3. Everything else (emails, meeting minutes, wikis, manuals, and so on)

Let’s talk about commit messages.

Code, commit messages, and comments are all forms of writing. In writing intended not as an expression of emotion but as a means of communication, clarity comes first. We already have the 5W1H framework as a tool for writing clearly. Rather than reinventing the wheel, we can use this familiar framework to ensure at least a basic level of clarity.

Some parts of 5W1H are handled automatically by version control systems such as Git:

  • Who (the committer)
  • When (the commit date)
  • Where (the branch)
  • What (the diff)
  • How (the diff)

Let the system handle the values it records automatically.

We should focus on the one thing it does not fill in for us: “why.”

Have you ever read code more than a year after it was written? Once code is several years old, even code I wrote myself invariably looks as though someone else wrote it. As I examine it, I inevitably find parts I cannot understand, and that is when I turn to the commit messages. Every piece of code has a story. Even if the reason was “just because,” there is still a story behind it: the author’s personal preference.

But what if the commit message is just a single line such as “Fix bug” or “Replace xxx with yyy”? I have no choice but to guess the story. If guessing feels too risky, I will probably avoid touching the code and work around it instead, because I do not know what might break. To prevent unintended consequences, I need to understand why it ended up that way and what led to the decision.

Code history, like a résumé, needs to tell a story. Otherwise, the product accumulates primordial mysteries that no one understands. Add Hyrum’s Law to the mix, and those mysteries become rules that must be preserved.

Other articles about commit messages make similar points. The Seven Rules of a Great Git Commit Message includes 7. Use the body to explain what and why, rather than how, while How Square Writes Commit Messages says that we should record the motivation for the archaeologists who will read our code.

So how should we record it?

The best approach is to be as specific as possible in the commit message. Ideally, it would include the background, process, and outcome of the decision, but realistically, documenting every commit in that much detail is difficult.

Personally, I prefer linking to an issue tracker, wiki, or another documentation system. A commit is immutable, which makes it hard to add more information later. Issue trackers and wikis, on the other hand, make it easier to provide detailed context and revise it afterward. Of course, keeping the connected system alive and preventing links from disappearing becomes just as important as version control itself, but I think the benefits make that responsibility worthwhile.

Remember: when comments or commit messages are inadequate, the person who eventually suffers in proportion to that inadequacy is me.

(Of course, perhaps it does not matter if you quit and run away… but leave a record for the unknown person who comes after you.)

When I look at commit messages or issue descriptions I wrote years ago, I do not have much room to talk. Still, I take some comfort in the fact that I now try my best not to repeat those mistakes. ( “)