Why A Good Commit Message Matters?

Yevgeny Gorbachev | July 18th, 2017

Time is money. Time is expensive. Time to market is twice as expensive. Time of a high-skilled developer is as much expensive as you could imagine. That’s why a good commit message matters.

“Context! Context! My kingdom for context!”

If you have been involved in a lot of different projects and worked with tons of source code bases during your career, you probably might read commit messages that are a total mess.

Here is a log fragment from the real code base:

What the changes were about? Why they were formatted so badly without keeping one style regardless the same code base? Who knows? It was a long time ago in a galaxy far, far away…

Then let’s compare them with the recent commits to the Spring framework on Github:

Which would you rather read? Which ones are concise and consistent?

A well-crafted commit message is the best way to communicate context about a change to other teammates. A source diff will tell what changed, but only the commit message can tell you why.

Peter Hutterer pointed it out:

• Any software project is a collaborative project. It has at least two developers, the original developer and the original developer a few weeks or months later when the train of thought has long left the station. This later self needs to reestablish the context of a particular piece of code each time a new bug occurs or a new feature needs to be implemented.
• Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it to as small as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

How a well-crafted commit message looks like

There’s no strict definition of the ideal commit, but in the company we try to follow the known best practices. Some of them I have written below.

Three questions

In accordance with Peter Hutterer, a good commit message should answer the three questions:

• Why is it necessary? It may fix a bug, it may add a feature, it may improve performance, reliability, stability, or just be a change for the sake of correctness.
• How does it address the issue? For short obvious patches this part can be omitted, but it should be a high level description of what the approach was.
• What effects does the patch have? (In addition to the obvious ones, this may include benchmarks, side effects, etc.)

These three questions establish the context for the actual code changes, put reviewers and others into the frame of mind to look at the diff and check if the approach chosen was correct.

One logical change

In general, a good commit should contain exactly one logical change. A logical change includes adding a new feature, fixing a specific bug, a code refactoring, etc. Don’t mix different changes from different areas within one commit, omit massive code changes in one commit as much as you can. It’s better to split them into several observable commits in accordance with the provided functionality. It will help reviewers a lot to understand the changes.

The seven rules

Chris Beams summarized the best practices of the great commit messages into the seven rules:

Keep in mind: This has all been said before.

1. Separate subject from body with a blank line.
2. Limit the subject line to 50 characters.
3. Capitalize the subject line.
4. Do not end the subject line with a period.
5. Use the imperative mood in the subject line.
6. Wrap the body at 72 characters.
7. Use the body to explain what and why vs. how.

For example:

The rules look quite simple but bring a lot. They put everybody on the same page, allow to keep the product’s consistency, properly track the changes, restore the rationale easily, without asking the author. Ironically, that author could be yourself several months earlier. But it doesn’t matter how long ago the changes have been done, and does the changes’ owner still work in the company in the same project.

Summarizing all the above, use the best practices, take care of your changes. Never forget, you are not alone, so a good commit message really matters.

Happy coding!