Is that feedback, or a dig?
In a code review, tone gets lost in transit. The same sentence can feel like a helping hand or a jab, depending on how the person reading it receives it. Conventional Comments solves this with an almost ridiculously simple idea: every comment says what kind of comment it is before saying anything else.
That variable name doesn't mean anything.
Flat. No tone of voice, no facial expression. Read on a Friday evening after two days spent on the pull request, it can easily sound like: you're sloppy.
nitpick (non-blocking): that variable name doesn't mean anything
Exactly the same words. But nitpick is the reviewer saying: “I know this is small.” The sting disappears without softening the message.
A code review is text. Just text.
No shrug. No half-smile. No “just thinking out loud.” Two people, two screens, often two time zones, and sometimes two native languages. All the cues that would tell you how much a remark matters in conversation are gone. Only the words remain.
The reviewer was in a hurry, so they kept it short. The author reads coldness where there was only brevity.
“This loop could be simpler.” A requirement or just an idea? The author can't tell, so they rewrite it. Two hours lost for nothing.
A junior developer gets fifteen comments. They don't see fifteen separate remarks. They see fifteen versions of “you can't do this job.” Twelve are minor. One actually matters.
A reviewer who doesn't want to upset anyone hedges every comment. Now nothing sounds important. The review is polite, vague, and useless.
None of these misunderstandings comes from a technical disagreement. They all come from the same thing: the reviewer's intent is nowhere in the text.
Every comment says what it is before saying what it has to say.
Conventional Comments is a convention published at conventionalcomments.org. The idea fits on one line: put a word in front of each comment to say what kind of remark it is. Optionally add, in parentheses, whether it blocks.
what kind (does it block): what you have to say
| What the reviewer writes | What the author hears |
|---|---|
| praise: the error handling here reads really well | Somebody took the time to notice what went right. |
| nitpick: this name could be shorter | It's minor — and the reviewer said so themselves. |
| question: why a 30 s timeout here? | I'm being asked, not accused. |
| suggestion (non-blocking): we could extract a method | An idea, not an instruction. My call. |
| issue (blocking): the session token is never invalidated | This is serious — and at least that's clear. |
The label doesn't change what you say. It tells the reader how to read it.
That's what sets Conventional Comments apart from the usual advice about “being kind in code reviews.” Nobody is asking you to soften every sentence, add emoji, or start with a compliment. You write what you were going to write. You simply put a word in front that makes your intent explicit.
The effort falls on the reviewer, not the person receiving the comment.
This is easy to miss at first. Choosing a label forces you to pause for a second and ask yourself what you're actually doing. And that second is often enough to defuse the comment before anyone reads it.
Putting nitpick in front of your own remark means acknowledging: “this is small.” The reviewer disarms the comment before it reaches the author.
People rarely remember to call out what went well. A button in a toolbar makes it easy. It's a simple mechanism, but it changes the tone of a review.
Marking something as blocking means owning that judgment. No more “anyway, I'll let you decide,” which commits nobody and leaves the author alone with the uncertainty.
Closing a point without acting on it means explaining why. A disagreement can't simply disappear in silence.
“This will make reviews toothless.”
The opposite happens. Without the convention, reviewers who don't want to hurt anyone tend to soften everything: “I was wondering whether maybe we could possibly…” Soon nothing sounds important, and the real problem disappears among all the hedging.
With a label, you can be direct without being harsh. issue (blocking): memory leak in the handler — that's a category, not a judgment about the person who wrote the code. Directness becomes easier precisely because the intent is explicit.
Without labels, the same review simply shows up as “15 comments.” Nothing else. That bare number is what can discourage a junior developer — not the comments themselves.
Good habits fade fast.
That's where this toolkit comes in — and only there. It doesn't teach people how to behave. It simply makes the habit easy to keep once nobody is consciously thinking about it anymore.
An extension that does the typing
A row of buttons sits above the comment box on GitHub. Type ?n and the extension inserts nitpick:. Hover over a button and it reminds you what the label means. Choosing the right label becomes effortless — which is exactly why people are still doing it weeks later.
Blocking points stay visible
The extension keeps track of unresolved blocking comments directly on the pull request and shows how many remain. Nobody has to scroll back through the thread to check.
It isn't there to police anyone. It's a safety net: an important point doesn't get lost somewhere in the thread.
The extension is all you need to get started. The convention itself needs no tooling at all. The tooling simply makes it easier to use consistently.
Assist and warn are available today. Enforce comes next.
The extension already covers the first two stages. Enforce will eventually add an authoritative, platform-level merge gate, independent of the browser. That capability is on the roadmap.
How teams adopt itYour comments never leave your browser.
What people write in a code review can be more sensitive than the code itself. The extension reads and checks everything locally. Nothing is sent anywhere. No telemetry. No account. No stored token. It runs only on the domains you have explicitly allowed — github.com included — and nowhere else.
There is one exception: your own settings — such as language and shortcuts — can follow your browser's sync if you have it enabled. Settings only. Never review content.
Enterprise Cloud · EMU
Enterprise Server
Server (self-hosted)
with documented limitations
Firefox
Open source · Apache-2.0
Start with one label in front of one sentence.
That's it. Everything else — the extension and its settings — exists only to make that habit easy to keep.