It might seem to many that this topic is quite insignificant, and should not take much space in the programming blogosphere. If you ever had to browse the history of several dozens of commits, trying to figure out which changes could have introduced a bug, and more importantly why, you understand the importance of it, for sure.
The issue with the generic commit messages is that they don’t provide enough history information. Once you find yourself looking into the file history, you’ll appreciate all the additional effort to which you, or your colleague, has put into thinking of a meaningful commit message. When you think about it, it’s not that much of an effort to think about what you have done and put it into writings for your future self.
You should avoid at all costs messages which don’t say what and why have you done changing the file. Examples of such messages are:
- blah – when you are pressed by your deadlines, you may think that you don’t have time to think about the messages you write. You may be tempted to just put anything into commit message to fool the commit policy checker. Still, once you get to read it, looking for a reason and place where a bug was introduced, the only one feeling like a fool will be you, reading just blah, blah, blah.
- Fixed issue, small fixes, further improvements, refactoring – once your project reaches mature stage, most probably many files will be touched in various bug fixes, improvements or refactoring. Having commit messages like these will only give you a hard time reading the file history and figuring out what was introduced when, and more importantly why.
- [#ISSUE_NUMBER] – this one is a bit better, because it ties the changes you made to a story where, hopefully, exists a detailed explanation of what and why needed to be changed at that moment. On the other hand, when you read commit history, the issue number, without an additional message doesn’t give you any information about the changes made. In order to figure out what happened there, you would need to go to your issue tracking system and read the description. Going back and forth between the source control and issue tracking system can take quite some time and energy.
Could you figure out which changes are made for each of these commits?
You must be wondering, what would be a good commit message then, if none of the above is.
Well, it’s a bit difficult to answer the question easily, but think how would it feel if you were able to read the project history as a story. Each line (commit message) should give you a hint of the changes that were pushed with it, and the context, why the given change was made. That would allow you to be able to figure out what was changed, just by quickly reading through it, without the need to actually look at the code changes, to see if the change in that particular commit could have potentially introduced the bug you’re fixing.
Have a look at these commit messages, taken from the Spring Boot history. You can get a pretty good idea about what was changed.
By now, I hope that you have a pretty good idea why good commit messages matter.
For a nice guideline on how to structure your commit messages, you could have a look at the Git documentation, chapter on Commit Guidelines.
How do you write your commit messages? Please feel free to share your thoughts.
Thanks for the article!
Thanks!