On Commit Descriptions

A commit description is about communication. It communicates context to code reviewers (if any) and to future code archaeologists trying to understand what came before (also if any). It's an essential part of The UX of Code.

What communication is necessary? The code diff describes in exquisite detail exactly what was changed. However, a higher-level overview is essential to framing those details and making them digestible to a reader in a reasonable amount of time.

• Why is this change needed, or what problem are we trying to solve?
• What's the high-level approach that was used in this commit to solve it?
• Why was this approach selected?

But this is an incomplete story. Notably, we're missing:

• Why should the reader believe this commit does what it purports to do?

... because if the code doesn't do what the description says it does, perhaps due to bugs or outdated commit text, then that description nearly useless. If, on the other hand, the test plan is robust and complete, then for many reviews the reviewer may not need to look at the code at all, comfortable in the author's test plan to enforce correctness.

The value of a good commit description is at least threefold:

Code Reviews

Many software engineers complain that reviewers take too long to do code reviews. If we make the reviewers' lives easier, if we reduce friction and minimize the mental energy required for them to accomplish their task, they're likely to do the review more quickly and more thoroughly.

• Is it obvious what the code does, and why? Or does the reviewer need to discover it on their own?
• Can they trust that the commit does what the description says, or do they need to examine it in great detail for correctness?
• Are there surprises in the code diff, changes that aren't explained in the commit description which the reviewer must then do extra work to understand? Or is every change clearly documented in the commit description, even if it's not part of the core feature being implemented?

Debugging

As software engineers, we all encounter bugs from time to time. Maybe we're examining a bug caught by routine testing. Or for a more stressful time, maybe we're investigating the root cause of a bug caught in production. In either case, ideally it should be fast and easy to learn where and how a bug was introduced.

Once we find the commit responsible for the bug:

• Can the reader look at the commit description and understand if they should trust the change?
• Can they reproduce the test plan to verify that it still works? Did the code ever work?
• Are there gaps in the test plan that may have allowed this bug to sneak in?
• Can the code author reflect on these gaps and consider how they might design better test plans in the future?

Code Archaeology

As software engineers, we're also bound to be digging into old code from time to time. Perhaps it's for debugging purposes, per the notes above. Perhaps we're looking to refactor or redesign a component. Perhaps we were writing code and discovered something surprising that we didn't understand, or couldn't remember.

There are countless reasons why a future reader will be trying to understand our code. But all of those readers need the same thing: context. A good commit description enshrines why code is implemented the way it is. Can the code be changed? Or is the existing behavior important in some subtle way?

Wrap-up

We might spend hours, days, or even weeks writing the code for a single commit or PR. Why do we then so often lack the patience to write more than a few words in the commit description? Be nice to the users of your code. They'll probably be either you or your colleagues. Spend two minutes to write a good commit description, with clear Description (Why, What) and Test Plan.

Take a look at a couple of your recent commits. How do the descriptions measure up? Is this what you'd want to see as a reviewer, when you're debugging a problem that might involve this commit, or when you're rereading the code two years from now?