Wrivio
Get Wrivio
7 min readBy Wrivio Team

How to Write Code Review Comments That Do Not Sound Harsh

A code review comment is one of the shortest things you write at work, and one of the easiest to get wrong. You have the diff open, you spot the problem, and you type the fastest accurate sentence you can: “This is wrong.” It is accurate. It is also the sentence the author will reread at 11pm.

The trouble is not that reviewers are unkind. It is that review comments strip out everything that softens speech: no tone of voice, no shrug, no “I might be missing something” in your expression. What remains is a terse instruction pinned to a line of someone’s work, visible to the whole team, and preserved in the history forever.

This is not an argument for padding every comment with compliments. It is an argument for writing comments that carry three pieces of information the author actually needs: what you noticed, why it matters, and whether it blocks the merge.

Comment On The Code, Never The Person

Google’s public engineering practices guide on writing review comments puts this plainly: make comments about the code, never about the developer. The difference is often a single pronoun.

Before:

Why did you write it this way? You’re doing two database calls in a loop.

After:

This loop makes two database calls per item, so a 500-row import becomes 1,000 queries. Could we fetch both sets up front and join them in memory?

The first version asks the author to defend a decision. The second describes the effect of the code and proposes a direction, which is something the author can simply act on.

Say Why, Not Just What

“Use a constant here” is an instruction. “Use a constant here, because this timeout appears in three files and they already disagree” is a reason. Reasons let the author judge the comment on its merits rather than on your seniority.

The Google guide makes the same point: a bit of explanation about your intent, or the practice you are following, helps the author understand and prioritize. You do not need an essay. One clause after “because” is usually enough.

Before:

Don’t catch generic exceptions.

After:

Catching every exception here will also swallow the timeout, so the retry logic above never fires. Could we catch only the parse error?

Label What Blocks The Merge

Most review friction is not about tone at all. It is about ambiguity: the author cannot tell which of your fourteen comments are must-fix and which are passing thoughts, so they treat all of them as mandatory and resent the review.

Fix that by labeling. The Google guide suggests prefixes such as “Optional” and “FYI” so authors know what is not required. Conventional Comments formalizes the idea with labels like praise, nitpick, suggestion, issue, and question, plus decorations like (blocking) and (non-blocking).

Before:

Rename this variable.

After:

nitpick (non-blocking): data2 doesn’t say much. Something like pendingInvoices would help the next reader, but this is fine to merge as is.

Whatever scheme you use, an unlabeled comment reads as an order. If it is not one, say so.

Ask Real Questions, Not Rhetorical Ones

A question is the right tool when you are genuinely unsure: “Does this handle an empty list, or is that guaranteed upstream?” The author may know something you do not, and the question leaves room for that.

A rhetorical question is the wrong tool. “Shouldn’t this be async?” is a statement wearing a question mark, and authors can tell. If you are confident, state it with your reason. If you are not, ask openly and mean it.

Praise Specifically, Or Not At All

A generic “LGTM, nice work” at the end of a review is fine, but it carries no information. Specific praise does: “Splitting the parser out made this much easier to review” tells the author which choice to repeat. Conventional Comments recommends the praise label for exactly this, and warns against false praise. Do not invent compliments to cushion criticism. Authors notice the pattern, and then they discount your real ones.

Move Long Disagreements Out Of The Thread

If a comment thread passes three rounds, the review tool is the wrong place for it. Written back-and-forth hardens positions, and every reply is public. Suggest a short call, then write the outcome back into the thread so the decision is on record for whoever reads the history later.

The same instinct applies when the problem is the whole approach rather than a line. A dozen line comments that all say “this design is wrong” in different ways are worse than one top-level comment that says it once, explains why, and proposes what to discuss. For broader guidance on criticism that has to survive being read twice, see how to give critical feedback in writing.

Using Wrivio On Review Comments

Rewriting tools are most useful here on the comments you already suspect are too sharp: the ones written fast, late, or annoyed. A Wrivio Context for code review comments could say:

Rewrite this as a code review comment to a teammate. Describe the effect of the code, not the person. Keep it under three sentences. Start with a label (nitpick, suggestion, issue, or question) and mark it blocking or non-blocking. Keep every identifier, file name, number, and code snippet exactly as written. Do not add praise that was not in the original, and do not soften a blocking issue into a suggestion.

Press Ctrl+Shift+Space over your review tool, paste the comment, and read the result before posting. Check that inline code survived untouched and that a real blocker still reads as one.

One practical note: review comments often quote proprietary code. If your team’s policy keeps source code off third-party services, switch to Local mode, which runs the model on your machine and makes no network calls during a rewrite. The tradeoffs are covered in what to keep local and what to send to the cloud.

The reviewer side is only half of a good review. The other half is the author giving reviewers what they need up front, which is covered in how to write a pull request description.

Common Questions

How do I point out a mistake in a code review without sounding rude?

Describe what the code does and what that causes, then suggest a direction: “This returns null when the list is empty, which will crash the caller on line 40. Could we return an empty list instead?” Avoid “you” and avoid “why did you”, and the comment reads as information rather than blame.

What does nit mean in a code review?

A nit, or nitpick, is a minor, usually stylistic point that the reviewer would like changed but that should not block the merge. Labeling it explicitly tells the author they can merge without addressing it.

Should every code review include positive comments?

Include praise when you mean it and can be specific about what worked. Forced praise used to cushion criticism tends to backfire, because authors learn to ignore it, including the praise you actually mean.

How long should a code review comment be?

Usually one to three sentences: what you noticed, why it matters, and whether it blocks. If you need more than a short paragraph, the issue is probably about the overall design and belongs in a single top-level comment or a short conversation.

What should I do when a review thread turns into an argument?

After two or three rounds, suggest a quick call instead of another reply, then post a one-line summary of what you agreed in the thread so the decision is recorded for anyone reading the history later.

Download Wrivio for Windows to turn the review comment you typed in a hurry into one your teammate can act on without wincing.