The Why

1 May 2019

Looking at a codebase, large or small, for the first time is always daunting. Lots of code and concepts that you don’t understand yet. It is great to have somebody to explain things to us. Why is this? Part of the reason is that the intent of the code is not always clear from just reading it. We are missing the “why”.

Revision control tools, from really old to more new including RCS, CVS, Subversion, Mercurial and Git do not just track versions of files. They also offer a logging functionality, so that you can go back in time, look at a particular change to a file and see a message written by another person explaining the change. Ideally!

We know that this is not always the case. It is unfortunately common to see a message accompanying a revision to be something like “refactor function ABC” or “move definition to other file”. We can see from the change that the function has been refactored; we didn’t need another message describing it too. Fortunately there is a really simple trick to make these commit messages genuinely useful bits of information.

When doing a git commit (or whatever), read the message and ask “why did we make this change?”. If the message doesn’t answer answer that question try and do it somehow.

Let’s do an (unrealistic) example. Consider the below pseudocode variables:

fd1 = 1
fd2 = 2
fd3 = 3

Let’s say we renamed fd1, 2 and 3 to stdin, stdout and stderr respectively. We look around and change the code everywhere. We make our commit and we are prompted for a message to go with it. It would be easy to write the message:

change name of variables

But our “why” test fails. The commit message doesn’t tell us “why” the change was made. A message which passes the “why” test could be this (if a bit verbose):

Give standard names to file descriptors

This matches the naming convention of C and Java. Using file descriptor abbreviation “fd” is maybe a bit too too low level for this program anyway.

Commit and push. A week later someone found a bug related to our change. Oh no! We know what’s coming next. It is the “why did you change this?” question in the daily meeting or in the chat system. We can avoid confusion and frustration immediately by looking at the commit log and read why the change was made.

Often a ticket number needs to be put with the commit message, so perhaps you don’t need to put any detail in the commit message at all. Consider putting a context in the commit message anyway. The code’s revision history will live longer and is more portable than any issue tracker’s database. Linking to an issue in an issue tracking system is only helpful if the “why” is clear in the issue, which is not always guaranteed anyway.