good_commit_messages.md

Different developers have different standards for and approaches to commit messages. In a broad sense, commit messages should be brief but descriptive.

Guidelines

• Messages should be lowercase, except where refering to a class name or other object that is syntactically required to be capitalized
  • add a navbar to the homepage is better than Add a Navbar to the homepage
• Messages should begin with a verb and have no subject
  • add a navbar to the homepage is better than I added a navbar to the homepage
• Initial verbs should be present tense; I prefer command form, but normal present tense is also okay; avoid present progressive (-ing)
  • add a navbar to the homepage is better than added a navbar to the homepage
  • adds a navbar to the homepage is better than adding a navbar to the homepage
• Where ambiguous, messages should indicate where a change was made
  • add image to photo gallery page is better than add image
  • Some developers dislike putting file names in commit messages, since someone browsing a repo can see what commits were made most recently in each file, but I am a believer in being as explicit as possible; when looking back at a list of commits made months ago, you want to be able to read the message and know what you coded without having to click into the commit and look at what changes were tracked
• Messages should indicate what the code does rather than what the code is
  • display all products is better than loop though all products and print them out

Different people will have different conventions, and it's important to remain consistent when working on a team. For example, if your coworker begins commit messages with normal present tense (adds, refactors) and you're used to using command tense (add, refactor), it is often good to adopt their convention for the duration of the project - that way, all commit messages within a respository follow the same conventions.