# 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.

Canonical URL: https://www.revix.ai/blog/how-to-write-a-great-pr-review-comment

Published: 2026-07-17 · Updated: 2026-10-11 · Author: Oscar Estudillo · Category: Guides

![A PR review comment annotated with its four parts: intent, severity, what breaks and why, and the fix](https://www.revix.ai/images/blog/comment-anatomy.webp)

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](https://www.revix.ai/blog/200-pull-requests-ai-code-review). 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](https://www.revix.ai/blog/what-is-ai-code-review).

## Conventional Comments, the open standard

We didn't invent this format. It is an open standard called [Conventional Comments](https://conventionalcomments.org), 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](https://www.revix.ai/blog/introducing-revix) covers what else it does. Try it on your next PR: [revix.ai](https://www.revix.ai).

## Related posts

- [What 200 Pull Requests Taught Us About AI Code Review](https://www.revix.ai/blog/200-pull-requests-ai-code-review)
- [What Is AI Code Review and How Does It Work?](https://www.revix.ai/blog/what-is-ai-code-review)