Conventional Comments

What it is

Conventional Comments is a short convention for code review comments, created by Paul Slaughter and published at conventionalcomments.org under a Creative Commons CC BY 3.0 licence. Each comment follows the pattern:

<label> [decorations]: <subject>

followed by an optional discussion. The core labels are praise, nitpick, suggestion, issue, todo, question, thought, chore and note, with optional extras such as typo, polish and quibble. Decorations add intent, most commonly (blocking), (non-blocking) and (if-minor).

A comment such as suggestion (non-blocking): extract this into a helper so the retry logic is tested once tells the author exactly what kind of comment it is and whether it must be addressed before merging.

Why it matters in a first job

Code review is where many new engineers first get uncomfortable feedback. A plain comment like "this is wrong" can read as harsh, and a junior often cannot tell a must-fix from a preference. Labels solve both problems:

• When receiving reviews, the label tells you whether a comment is a blocker, a suggestion or a question, so you respond in proportion and do not treat every nitpick as a failure.
• When reviewing others, labels make it easier to comment on a senior engineer's pull request. A question: is a safe way to ask why something works without implying it is wrong, and praise: reminds you to say what is good.

How to use it

1. Read the one-page site (about ten minutes).
2. Before using it on your team, check whether the team already has a review convention. Some teams use it formally; many use a looser version such as prefixing "nit:" for minor points.
3. Start with just three labels in your own reviews: question, suggestion and issue, each with blocking or non-blocking.

Free vs paid

Free. There are browser extensions and editor snippets built by the community, but you do not need any tools.

Is it worth it?

Yes, for the cost of ten minutes. It is especially helpful if English is your second language, because the label carries the tone that is hard to get right in a short comment.

Common questions

Will my team think I am being formal? Occasionally. If the team does not use labels, keep the habit of making intent clear ("small thing, not blocking:") without the exact syntax.

Does it replace a review guide? No. Pair it with Google's engineering practices guide, which explains what to look for in a review; Conventional Comments is only about how to write the comment.