Friday, June 30, 2017

How to Write Effective Commit Messages

When committing code to a source code repository, it is generally expected that we write some kind of comment to say what the change is all about. As we scroll through the history of changes we can see the comments for each commit. While there are variants of how we write our comments, I've found that following a simple formula can produce comments that provide the most value.

There are several problems when we write vague or disparate comments - consider it a smell. Either the work being done is nebulous or too big to pin down as in "doing work" or "cleaning up" or "refactor". Or the commenter isn't communicating well or worse yet, has no connection to the output of their work - "made tables" or "wrote code for beta" or "found a better way to do it".

The reason each of these types of comments are issues is that they don't communicate well to others - including your future self. As we scroll through source history looking for some past breaking change, we'd like to see specifics about each change.

It's good if you write comments like this:

    "[Issue #174] adding user type so Admins can login."

It has the following structure:

    "[<issue>] <what> so <why>"

First, the issue call out is formatted in a parse-able way - one day you may want to run a query on all comments and consistent formatting will help big time! More importantly, it links the change to an actual issue for reference otherwise there is no further context for the change. In some version control systems/integrations, you can actually link check-ins to issues. If you've got that setup, it's not strictly necessary to include the issue in the comment.

Next is <what> you are doing. Be brief in the first line. Make this something everyone can understand - make it relevant to users even. In this way, updates can easily be conveyed to users at deployment time! You can put details on subsequent lines if they aren't already in the issue itself or if they would be relevant to further understanding the change - but do so sparingly...the code and comments in the issue should speak for the details already.

Following <what> is <why>. I really like to include the why part because it allows other developers and your future self to understand at a glance why you made that change. More importantly, it gives product owners/managers some context to the changes that are being made with the same at-a-glance view. Communication with those folks can be facilitated via a dump of changes since last time! Of course with the proper tracking system this isn't the only way...but it is a handy tool for prepping a release.


Consider - we write code for consumers and will have to communicate to consumers about changes, commit comments is a big part of the glue between the incoming work and the outgoing product. Take the time to make them clear and concise for a better overall product experience!