How to Write a Great PR Review Comment

A great PR review comment says what is wrong, how much it matters, and how to fix it. "This function is a mess" does none of that. It leaves the author guessing what to change, how urgent it is, and whether it blocks the merge.

The four parts of a good PR review comment

1. Be specific. Point at the exact line and behavior. Write "this loop re-queries the database on every iteration," not "this is confusing."
2. Tag it. Start with praise, issue, question, nitpick, or suggestion, so the reader knows what kind of comment it is.
3. Rate it. Blocking or non-blocking. Does this hold up the merge, or is it safe to ship as is?
4. Point to a fix. Give the author a way out, not just a complaint.

The one-line shape

Together they make one shape: tag (severity): what's wrong, and the way out.

Before and after examples

Blocking issues

Name the function, what breaks, and the fix:

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.

Non-blocking nitpicks

Severity works the other way 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.

Questions

Not every comment is a verdict. Ask a real question and you get a real answer. Otherwise the author defends 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

Make praise as specific 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.

Fewer, better comments get read

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. A reviewer that comments on everything gets scrolled past, whatever format it uses. That is one of the things to test before you buy one.

Conventional Comments, the open standard

We didn't invent this format. It is an open standard called Conventional Comments, and any team can use it today, with or without a tool.

Revix AI applies it for you: every comment it posts on your PRs starts with a Conventional Comments label. The launch post covers what else it does. Try it on your next PR: revix.ai.