Writing commit messages is something that every programmer has to face at some point. It may be as early as when starting to contribute to an open source project from home or it can be as late as when joining a job where the development team uses a Version Control System (VCS for short). (Off topic tip: if an open source project or a job you join do not use any VCS, consider twice thrice if you want to do so.)
You need to remember that whatever you write in a commit message will be left behind for posterity. Additionally, commit messages, along with the annotate functionality of most VCS systems, are an invaluable tool when hunting down bugs that seemingly pop up from nowhere. Therefore, you must pay special care to write sensible and readable messages. These messages are not for yourself: they are for your peers and for future generations so that they can easily inspect what happened to a piece of code.
Here are my top 5 guidelines to write good commit messages:
No. 1: Detail the what and the why, not the how
Commit messages are part of the history of the project, and exist to detail what changed at every point in time and why such changes happened. Whatever it is that you are checking in — be it code, documentation, pictures, etc. — already details the how of a change.
For example: "add function check_flags and call it from main" is a horrible commit message whereas "fix main to properly validate the input flags" is a better version of it. Note, however, that a message of the form "add function find_window" could be perfectly acceptable if was describing a change in the public API of a library.
No. 2: Be thorough but concise
The readers of your commit message should not need to look at the change itself to understand what happened to the tree: reading the commit log should be sufficient for that. Therefore, make sure you detail precisely, at a high semantical level, everything that has changed in the code.
Note that, as you do this, you may find yourself explaining two different and unrelated things that have been modified. This is especially true if your commit message ends up being a list of bullet points. If that is the case, you should really consider splitting the change apart and committing two independent changes, each with its own log message.
No. 3: Restrict the first line to the "subject"
Split your commit message into a one-liner summary (aka the subject) and a more detailed explanation of what happened.
The rationale for this is that most VCS tools and graphical/web front-ends use the very first line of the commit message in terse lists. Such lists provide the reader an excellent way to quickly get an idea of the major changes that have happened to a file or a tree, and for these to be useful the short views of the commit messages need to be useful.
Side-note: If you use Vim to compose commit messages for Git, you will even notice that the maximum length of the first line is restricted and denoted by a different color.
No. 4: Use the present tense in the first person
Write commit messages in the present tense, using the first person. This is just the most widespread style and if you use something else your messages will read strange.
| No | Adding feature X |
| Adds feature X | |
| Added feature X | |
| Yes | Add feature X |
But be aware: consistency is better than doing as I mention here. If you are joining an existing team and that team has a specific way to write messages, copy their style. Spend some minutes digging through old commit logs to learn the behavior of the team.
No. 5: Watch out your spelling and grammar
Once again, remember that your commit message will be left behind in the source tree for posterity's sake. It is important that you watch out your spelling and your grammar in order to write text that is pleasant to read, has no typos and transmits the right information. The same rules as when writing code apply: if you are sloppy in your writing, why should one believe that you are not sloppy in your code?
To conclude: no matter how nice your commit messages look like, they are no replacement for a hand-written NEWS file. More on this on the next post!
