Let’s Talk About Writing Good Commit Messages

Good commit messages are ones that help the reviewer easily understand your code. It's helpful to think of three kinds of information that can be included in a commit message:

1. Syntactical
2. Behavioral
3. Motivational

Syntactical

Syntactical information describes the literal code change, from the perspective of the code. Examples:

• Inline method: User#authenticate.
• Fix typo in sign-up message.
• Use left outer join instead of inner join.
• Combine two css rules.

This type of information is the most-readily at hand to the author. It's the easiest commit message to come up with, but it's also the least useful. This is hardly a "good" commit message, but it's probably acceptable in a few special cases:

1. The change is a change of form, only, and the desirability of the new form is well-understood and agreed-upon, e.g. in linting rules, or
2. The change is extremely trivial, and behavioral and motivational aspects are extremely obvious.

Behavioral

Behavioral information describes the code change according to how it changes the behavior of the software. This can only apply to functional changes. Examples:

• Delay sending the user authentication reminder.
• Use a bigger font for the login message.
• Warn the user about excessive login attempts.

Behavioral information is much more useful than syntactic information for readers of commit messages (i.e. reviewers). Good commit messages for functional changes always include a behavioral description. Often, it's helpful to describe not only the behavior after the change, but the behavior before the change, in order to explain how it's changing.

Motivational

Motivational information answers the question, 'But, why?' This is where best commit messages dwell. They justify the change by explaining the benefit of the new behavior. Examples:

• Prevent hackers from inferring username existence from authentication errors.
• Prevent user confusion about password requirements.
• Encourage wider use of new features by providing tool-tips.
• Avoid confusion between two similar method names.

All these examples are brief. Real messages are often longer and combine multiple categories of information. Notice that motivational explanations can apply to both functional changes and to non-functional changes. All commit messages deserve motivational explanations, except those where the motivation is embarrassingly obvious, and even some of those! If you do the work of including motivational information, you'll probably find that any syntactic information is frivolous and extraneous, so leave it out.

Code reviewers are seeking to understand both what you changed, and why. They have the task of judging whether or not your changes are correct, complete, clear and concise. Having a great commit message communicates your changes more effectively and makes their difficult task easier.

So, tl;dr, Firstly, say WHY you want to change the code. Secondly, say HOW you want to change the code. Only if you can't do either of those, say THAT you changed the code.

Here at MojoTech Peer code review is an integral part of our process. As professional software engineers, we believe that a strong review process helps us ensure that the code we are writing is of the highest quality. Learn more by reading "The 4 C’s for Evaluating Code Quality".