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 expensive as you could imagine. That’s why a good commit message matters.
If you’ve been involved in a lot of different projects and worked with tons of source codebases during your career, you probably read commit messages that were a total mess.
Here is a log fragment from a real codebase:
What were the changes? Why were they formatted so badly without keeping one style in the same codebase? Who knows… It all happened a long time ago and in a galaxy far, far away…
Let’s compare the fragment above with the recent commits to the Spring framework on Github:
Which would you rather read? Which commits look concise and consistent?
A well-crafted commit message is the best way to convey the context of a change to other teammates. A source diff will tell what has changed, but only the commit message can tell why.
Peter Hutterer pointed it out:
There’s no strict definition of an ideal commit, but in our company, we try to follow the known best practices. Some of them I’ll share below.
According to Peter Hutterer, a good commit message should answer the three questions:
These three questions establish the context for the actual code changes, allow reviewers and others to look at the diff, and check if the chosen approach was correct.
In general, a good commit should contain exactly one logical change. It may include adding a new feature, fixing a specific bug, code refactoring, etc. Don’t mix different changes from different areas in the same commit, omit bulk code changes in one commit as much as possible. It’s better to split them into several observable commits based on the functionality provided. It will greatly help reviewers understand the changes.
Chris Beams summarized the best practices of the great commit messages into the seven rules:
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, and restore the rationale easily, without asking the author. Ironically, that author could be you several months earlier. It really doesn’t matter how long ago the changes were made and whether the changes’ owner still works in the company or on the same project.
Summarizing all the above, use the best practices and take care of your changes. Always remember, you are not the only one involved, so a good commit message really matters.