/* Code-Comments */

Writing Better Commit Messages

In a recent sprint retrospective, a teammate mentioned that we could help ourselves by adding more context to our pull requests. This got me thinking and I started reading about how other teams handled this problem. This search led me to three resources which are changing the way I’m thinking about commits:

  1. “My favourite Git commit” by David Thompson | Fatbusinessman.com - A blog post which breaks down one particularly noteworthy commit
  2. “A Branch In Time” by Tekin Süleyman | tekin.co.uk - A conference talk recorded at RubyConf AU 2019
  3. “Telling stories through your commits” by Joel Chippindale | Mocoso.co.uk - A conference talk from The Lead Developer UK 2016

Joel Chippindale’s talk, “Telling stories through your commits,” presented a three pronged framework for writing effective commits which I intend to use as a bit of a checklist for the near future:

  1. Atomic commits
  2. Meaningful commit messages
  3. Revise history before sharing

What do they mean?

Atomic commits are the “minimum viable commit.” It’s the smallest chunk of code that together means something. Here, the --patch flag (also -p) of git add is particularly useful. A heuristic to use: If you need to use “and” to describe the commit, it may be too big.

Meaningful commit messages are described in four parts:

  1. Short one line title,1 e.g., “Fix Widget Bug.”
  2. (As necessary) a longer description of what the change does. This can include a reference to the project management software, though as Tekin pointed out in his talk, this can backfire when the tracking software changes (e.g., move from Trello to Jira to RoadmapAllstar2)
  3. Why the change was made
  4. (Optional) Discussion of alternative approaches evaluated

Revising history before sharing was probably the most eye opening for me. It was an argument for using git rebase --interactive in a way to help organize commits to tell a story. If the point of the commit is to communicate to a future developer what happend and why, then eliminating noise of commits like fix typo and linting makes that easier.

While these are trivial examples, Joel provided really interesting ones - like reorganizing the order of commits and merging them to be more complete units (e.g., combining a change with the test case written to cover it rather than leaving those as two separate commits).

I thought I was doing alright with my commits, but what David, Tekin, and Joel showed me was that there’s so much more I can do - not just to help myself, but to help my team.

There are things I can start doing today that will help me and my team be more productive that cost me very little.

Footnotes

  • 1 While he didn’t reference it explicitly, the examples Joel provided reminded me of Google’s Engineering Practices Documentation.
  • 2 Okay, I made that one up, but admit it, you weren’t sure for a moment!

Thanks for reading! My name's Stephen Weiss. I live in Chicago with my wife, Kate, and dog, Finn.
Click here to see the archives of my weeks in review and sign up yourself!