Write good commit messages

Dear new developer,

Take the time to write good commit messages. Such messages communicate intent across time, and live very close to the code. Here’s an example of a bad commit message:

Updated the code.

There’s no intent here. Yes, of course, you did update the code. Why? Inquiring minds want to know.

updated the acceptForm method to accept a URL escaped code

This is slightly better, but is still no good. This is a bad commit message because it focuses on the how but not the why. Why did the acceptForm method need to be modified?

In general, great commit messages focus on the intent of the change, not the mechanics. Why was this change needed? What drove it? What would you want to know about this reasoning or decision a year from now? What would you want a new team member approaching this code base to know? These are good questions to guide you as you consider your commit message.

Document the reason for the change because those reasons can get lost. They may be captured in a doc, yes, but git log is far more accessible than a doc. In some teams and situations, you won’t even have a document to capture the purpose of the change; it might have been just a hallway discussion, a ticket filed by a customer, or a change made by a single developer without consultation. Code reviews and pull requests can help capture intent as well, but again, they may or may not be easy to find; they certainly won’t be as easy as git blame.

Here’s a good commit message:

Updated the acceptForm method to except a URL escaped code.

Client ABC was sending a URL escaped code instead of what we expected. This means that the system was throwing a null pointer exception. Investigated changing client ABC, but that would involve releasing another version of the client library, which we are deprecating.

More details in this thread: http://slack.com/aaa/bbb

[#123]

Feel free to write as much as you need to communicate intent. It’s also good to have a summation in the first line, then two newlines and then as much explanatory text as you want. I like to do this on the command line so that it’s easy to edit.

If the mechanics are particularly tricky or misleading, that’s one time you may want to focus on the how. For example, if a piece of code is purposefully using a particular deprecated data structure for compatability reasons, outline that in the commit message.

An additional benefit is that this forces you to think about what you were trying to accomplish with this change. If you make more than one change at a time, you can use git add -p to commit only a section of a file.

If you make a mistake and you are using git and haven’t pushed to a remote, you can use the --amend command to make a change to the most recent commit message. You can also use the git rebase command to rework your entire commit structure, including getting rid of “there was a typo” commit messages. Here’s a video about a rebase workflow:

Now, I’m definitely not perfect about this. I sometimes make errors in my messages. In that case, just as when I make any other mistake, I find out what I did wrong and try to do better next time. You can also use tooling to avoid errors. I have heard of people use tools like Gitcop to enforce rules, but haven’t used it myself.

You can also add a git hook, as a team require all feature branches to reference an issue number, and parse the branch to put the issue number on every commit. Or you can modify that git hook to append the branch name, as outlined here. I’ve done this on different teams and it’s low effort and effective. This isn’t perfect because you can still have a commit with a one word message, but at the least you have some link between a code change and the impetus for it.

Whatever you do, find out what the team norms are around this. Have your commits meet at least that level of detail. This norm may be delivered when you start, or via code reviews, but you can ask as well: “what are some great commit messages that I should model mine after?”

Remember, the purpose of a commit message is to communicate intent. Strive to do that and you’ll thank yourself later when you’re trying to figure out what is going on.

Sincerely,

Dan