How to write a proper commit message

No matter what versioning system you are using (Git, Mercurial, Subversion, TFS, CVS), a useful commit message is just as valuable as adhering to coding style and leaving behind useful comments.

Why care about commit messages?

1. If you ever need to look back through the commit log to find when a change was introduced, you will be reading the commit log. Poorly done commit messages require diffing the files to discover what happened.
2. In open source projects a lieutenant or BDFL will be reading the commit message, and deciding to go forward based on the content. The commit message serves as documentation but partly as a marketing blurb for you in that case. I have seen pull requests rejected solely on the basis of a nonconforming commit message.

Examples of poor commit messages:

"" - a blank commit message is totally useless, the shame!!!!

"bug fix" - doesn't describe what was fixed or why

"minor updates" - doesn't describe what was done, minor is a relative term

"adds button" - doesn't describe what button was added where or what it does

"typo" -  where was the typo? how to confirm it is fixed?

Recipe for a good commit message:

1. Include the issue number at the start of the commit message.
2. Include the module or section of the application.
3. Describe the outcome from the end user’s perspective, changes to business logic, changes to defaults, behaviors, etc.
4. Justify the solution. This may not be necessary if you can explain more about the commit in the issue tracking system (and you followed step #1 so the commit and the issue tracker are cross referenced). In open source projects, the commit message might be the only place to justify your approach though.
5. Some projects are very strict about the length of the commit message’s first line. The standard is 50-60 characters with a max of 72 for the first line of a commit message in Git. That has to do with the fact that Git users, including its founder Linus, are predominantly console users.
6. Follow the team’s post commit hook standards. For example if the commit starts with “Fixes #123” it might push issue #123 to QA.

Examples of good commit messages:

XYZ-1234 Backend support for multiple currencies

Everywhere a currency field is rendered the Money object automatically formats the data properly in the user's currency format. No changes to the UI code. Modules that use currencies include pricing, checkout, shipping estimation. Backend changes fully unit tested.

XYZ-999 Fixes typo on login page

The login page had a link to the forgot password page spelled 'phorget'. HTML level change. No other cases of 'phorget' present in code base.

Other tips about committing code:

• Read your own code and the diff before committing. I cannot tell you how many bugs I’ve caught in my own code by performing this simple task. Sometimes I get up, take a little walk, then come back and look at my code with my QA hat on. It is hard to break down your own masterpiece, but the better you get at it, the more of a true master you will become.  So before committing that next chunk of code, ask yourself:
  • Is this up to snuff quality wise?  Would you want your co-workers to read it in the state it is in?
  • Is this code properly formatted?
  • Are the complex sections adequately commented?
  • What if variable X is the wrong type or null (think of null pointers in Java, string vs numeric in Javascript).
  • What if an unexpected input is passed in?
  • Are all the corner cases in the unit tests covered?
  • Any straggling TODO items that need to be cleaned up?
  • Spelling / grammatical errors anywhere?
• Never mix a white space or formatting changes with a logic change. That makes it a nightmare for the next person to figure out which changes were relevant to the program’s logic and which changes were just formatting updates.
• Commit in atomic related units. A commit should not include changes to unrelated sections of the code.
• Favor smaller commits vs one HUGE commit.