On Commit Descriptions

M. Treaster 2024-09-22

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.

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

... 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.

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:

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?