Commitment issues

You’ve been spending plenty of time together. You’ve had your ups and downs. As time’s gone on you’ve realised you like the way things are going and it’s time to commit.

Writing effective, communicative commit messages can make the world of difference to other members of your team. Just as with code comments or clear variable and function naming, good commit messages are worth putting some thought into.

First and foremost focus on communicating why the changes are being made. It’s easy to think commit messages are actually about what has changed, but reviewing the code will show you that. Why the code has change lets people know the intent of the change rather than the details of it. Good examples of commit titles are:

  • Update interface to the new branding
  • Add Dutch translation
  • Remove reference to Batmans true identity
  • Add GDPR compliance message

Once you’ve nailed your title follow up with a good description. For example:

Remove reference to Batmans true identity

The copyright text on Batmans website specifiys the copyright holder as “Wayne Enterprises”. This suggests that Batman has some association with the organisation. This update removes all connection between the two entities, protecting all parties. This fix addresses issue #391.

As you can see this message doesn’t contain any details about the code. It clearly highlights why the commit is being made and also connects the commit to a reported issue if one exists.