Last time we talked about version control, so let’s elaborate a bit on that. One of the aspects of using version control is the possibility of commenting on changes you do in the code. Actually, it shouldn’t be only the possibility, it should be a necessity.
Git documentation provides a standard template and guidelines for commit message, let’s have a look.
Capitalized, short (50 chars or less) summary
More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run thetwo together.
Write your commit message in the imperative: “Fix bug” and not “Fixed bug” or “Fixes bug.” This convention matches up with commit messages generated by commands like git merge and git revert.
Further paragraphs come after blank lines.
– Bullet points are okay, too
– Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here
The most important question to be answered by the commit message, is what happened. Think of list of commit headers as a news feed about your project or headlines in the newspaper. You want to know what happened first. Then, usually, why this happened and maybe some more details about it. But not too much. Remember one of Agile Manifesto ideas: Working software over comprehensive documentation.
You are talking about changes, so use active voice. Choose a tense you want to use and stick to it, so the story of your project is coherent. Try to be useful – will the message be helpful to person that is going to investigate production crash in the middle of Saturday night after your changes?
Keep your emotions at bay. Sometimes you would like to shout and cry over the code you have to work with when committing. You can grab a few beer with your fellow developers after work and explain them in detail why your architecture is dumb as an ox. Do it in the bar, not in the commit message.
How detailed should be the message? It depends on many things. If you are working on small two man project, and the second developer is right in front of you, there is probably no need to write a poem each time you commit. If you work on huge open source monster with hundreds of people you haven’t ever seen, nor had planning and review with, it’s a different story.
If you need to write a lot about your change to explain it, perhaps version control is not the best place to do so. Reading commit message should quickly and precisely tell you what was changed and why, not explain in details the architectural nuances it is connected with. We have a documentation for that. There are people who read Clean Code chapter on self documenting code, misunderstood it and are now trying to sabotage any other form of documentation “because Uncle Bob said…”. No, that’s not what Uncle Bob said.
If the change requires detailed explanation, just point to it. Your product should be accompanied by some form of Product Backlog and most commits should belong to some kind of user story, task, feature or whatever you have there. I don’t believe it should be all of them, because sometimes you just randomly walk into small and ugly piece of code that you can safely fix ad hoc, since you are the Good Scout. Assigning this change to any unrelated existing story is artificial, and creating separate story just for this change might take more time than performing the change itself. If your workflow requires that all changes need to have a story, perhaps you can have one story called Scouting or something like that. Before you start the story, it should contain a business description of what is to be done. During development, you might want to use issue tracking software to store more detailed explanations of changes than in the commit messages.
Sometimes you might want to include some additional external documentation or knowledge base outside of issue tracking system. Perhaps you have some form of wiki, Confluence, Google docs or other form of organizing documentation and can describe why something happened in there. You might want to create a technical background to cover business story. Perhaps write down some problems you have encountered, motivate some choices you have made and list potential risks you see. You can discuss things with other developers on the project, ask decision-making people to make decisions or request comments.
Why are we doing this, again?
Just remember, that all this should be there to help, not to restrain or annoy. If it is not helping, don’t hesitate to change it or kill it. With fire, to be sure.