"This function is a mess" is not feedback. It's a feeling, and it leaves the author guessing what to fix, how urgent it is, and whether it's blocking the merge. The four-part shape below removes the guesswork.

The shape of a good comment

Be specific. Point at the exact line and behavior. Not "this is confusing" but "this loop re-queries the database on every iteration."
Tag it. praise, issue, question, nitpick, or suggestion, set before the first word, so the reader knows what they're walking into.
Rate it. Blocking or non-blocking. Does this hold up the merge, or is it safe to ship as is?
Point to a fix. Not just a complaint. A direction out.

Put together, every good comment fits one shape: tag (severity): what's wrong, and the way out.

Here's the difference it makes:

Before

"This function is a mess."

After

issue (blocking): processOrder does validation, payment, and email in one function. A failed email rolls back a charged payment. Split it so each step can fail on its own.

Severity works the other direction too. Tag a preference non-blocking and nobody has to defend it like a bug:

Before

"Why aren't you using a map here?"

After

nitpick (non-blocking): Could swap this loop for a lookup map. Cleaner, but fine to leave.

Not every comment is a verdict. Ask a real question and you get a real answer, instead of an author defending code against a suspicion you never stated:

Before

"This seems wrong?"

After

question: Does this need to handle userId being null, or is that guaranteed upstream? If it's guaranteed, we can drop the check below.

Praise deserves the same specificity as criticism. Naming the decision is what makes someone repeat it:

Before

"nice"

After

praise: Good call pulling out retryWithBackoff. That kind of thing gets copy-pasted wrong everywhere. Reusing it is the right move.

A well-shaped comment still has to be worth reading. Across our first 200 reviews, 70% of what Revix posted flagged something the team acted on. Volume undoes shape: a reviewer that comments on everything gets scrolled past whatever format it uses, which is one of the things to test before you buy one.

This isn't a system we invented. It's an open standard called Conventional Comments, and any team can start using it today, tool or no tool.

Revix AI just applies it automatically. Every comment it posts on your PRs comes pre-tagged by intent and severity, so authors fix what matters first. That's one piece of what it does, and the launch post covers the rest. Try it on your next PR: revix.ai.

The shape of a good comment

Keep reading