Any software project is a collaborative one. It includes at least two developers, the first developer that starts working on a project and the same developer but a few weeks or months later when the train of thought has long left the station. The second one has 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. But since we can’t avoid it completely, our efforts should go into making it as short as possible. Commit messages can do exactly that. As a result, a good commit message indicates whether a developer is a good collaborator.
How a well-crafted commit message looks like
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.
Why is it necessary? It may fix a bug, add a feature, 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 in other cases, 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, allow reviewers and others to look at the diff, and check if the chosen approach was correct.
One logical change
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.
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.
Setronica is a software engineering company that provides a wide range of services, from software products to core business applications. We offer consulting, development, testing, infrastructure support, and cloud management services to enterprises. We apply the knowledge, skills, and Agile methodology of project management to integrate software development and business objectives effectively and efficiently.
Strictly Necessary Cookies
Strictly Necessary Cookie should be enabled at all times so that we can save your preferences for cookie settings.