When you open up a project and go through the long list of commit messages, most of the time you would realise that its a mess. A clear and concise commit message would do wonders for the long run of your project and help other developers and colleagues to better understand what is being implemented in your commits, would help in speeding up the review process and track good release notes. Lets look into some of the best practices that you can adopt to write good commit messages:
1. Single Line. Short and Precise.
Its always good to stick your commit message to a single line with an average of 50 characters (not a mandatory though). It just makes the commit message more readable. GitHub enforces this character limit strictly and wouldnt allow you to type more than 72 characters.
2. Differentiate Subject Header and Body
One good idea you can stick to while writing out commit messages is to seperate the subject and the body of the message with a single line inbetween. If you have a hard time thinking on write down everything you want to convey in a single line, just feel free to explain it in multi line description making sure you seperate it from the subject with alteast a single line inbetween.
3. Present Tense and not Past Tense
Whenever you write out your message write it such a way that its in present tense and not in past tense. Making the message in an imperative way can sound a bit rude and believe what, even GIT uses the same mood when making auto commit messages. A simple example would be the commit message that GIT writes when performing the merge operation:
Merge branch 'my-branch-name'
Below are good examples for imperative commit messages:
1. Fix login issue
2. Upgrade version 2.3
3. Implement Code Optimization
4. Replace deprecated functions
Below are examples on how to NOT write commit messages:
1. Implemented Brand new API calls
2. Fixed Login Issue
3. Removed the unwanted codes
4. More code for bugs fixes
We can simplify this process by trying to fillout the space here with your commit subject:
This commit message will <Your Commit Subject Here>
4. Using "Reference or Tracking Numbers"
Including Ticket Numbers or Tracking numbers that are generated for Bugs or support tickets would make the review process a piece of cake. The reviewer of your tasks would be happy that you did so. Just include the ticket number before the subject line and that would take care of explaining everything about the code and the task that you have worked on and committed. Below is an example:
"#84578 - Fix IE Browser Compatibility Issue"
Incase of working in a collaborative project, organizations can define shorthands prefixes like the below for easy identification:
"[css, js]", "BugFixes:", "Support:"
5. Listing of points using hyphens or asterisks
When it comes to describing commits, bullet points are ok too.
Typically an hyphen or asterisks can be used to denote bullet points in commit messages followed by a single space and a line in between each points. Using bullet points in commit messages make it more readable and also easy for the developer to list out the tasks completed in the commit.
6. Capitalize the Subjects:
Though this one looks so simple, following these subtle things can make your commits look more standard and consistent. Begin your subjects with Capital letter or you even write it in Upper Camel Case.
7. No Periods for Subject lines:
Subject lines are nothing but heading / titles and title do not end with a period. Hence do not stick to the practice of ending subject lines with a period.