How to Write a Great PR Review Comment
Most PR comments waste the author's time because they never say what they actually want. Here is the four-part format that fixes that.
"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. Here's the four-part shape that 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:
"This function is a mess."
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:
"Why aren't you using a map here?"
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:
"This seems wrong?"
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:
"nice"
praise: Good call pulling out retryWithBackoff. That kind of thing gets copy-pasted wrong everywhere. Reusing it is the right move.
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: userevix.com.