It’s been several months since I started sneaking conventional comments into my code reviews.

Ever read feedback from a reviewer and found yourself staring at the screen with a “…what do you want from me” face? Yeah, me too.

Conventional comments

Conventional comments is a neat little framework to help you say exactly what the issue is, why you’re bringing it up, and how seriously the other person should take it.

Without them, the code review process can burn hours (or days) on pure miscommunication:

People spend hours fixing “nice-to-have” stuff while the real show-stoppers hide until the last second.
Reviewees and reviewers get into long debates over points that aren’t critical for the merge request.
Sometimes, reviewees spend days building something, then find out the reviewer had a completely different approach in mind.
And sometimes, the reviewee has no idea what the next move is, so they burn time asking, “Wait, do you want me to actually change this, or…?”

Side note: “Next move” doesn’t always mean “change this code”. Sometimes it’s more like “This bit doesn’t feel right. I don’t have the answer, go dig into it and see what you find.”

With conventional comments, you’re not just pointing out problems, you’re giving them a clear map for what to do next.

My usual toolkit

Refer to the official conventional comments site for the full list of labels and decorations, but I usually grab the classics:

blocking / non-blocking -> basically, “No merge until this is fixed” vs. “Meh, up to you.”
nitpick -> tiny, subjective stuff that could go either way.

You can get creative and use labels or decorations beyond the ones in the docs. For example, I use sharing or pro-tip to indicate that the comment is purely for knowledge sharing. You can also use labels like think-out-loud or ramble when you’re not entirely sure what you’re talking about but want to put ideas on the table and invite more thoughts.

Same label, different meaning

Labels can mean slightly different things depending on your team setup.

In a strong-ownership model (where one person fully owns a code area and is held accountable for its quality, long-term direction, and any production issues that arise), (blocking) literally means blocking, “I can stop this PR if my point isn’t addressed” (Principle of parity of authority and responsibility).

If it’s more shared ownership (everyone can touch everything) and the reviewer is simply another pair of eyes, (blocking) might just mean: “I think this is a bad idea to skip, but hey it’s your code. Just… don’t say I didn’t warn you.”

Loosely following the rules

I don’t label every comment. If something’s obviously wrong (e.g. “This endpoint is too sensitive to leave open to the public”), I’ll just say it. But even then, the mental checklist is still there: How serious is it? Must it be fixed? Will they know what to do next?

Next time you’re reviewing code, try tossing in a conventional comment, or at least ask yourself: Will this help them move forward, or just leave them with a blank stare?