Why your code review comments sound harsher than you meant

You left fourteen comments on a pull request this morning, somewhere between standup and your next meeting. Twelve were small. One just said "nice". One was actually important — the retry logic could charge someone twice.

By lunch the author has replied "done" to all fourteen. Including the one that was a question. And in the afternoon they're a little short with you in chat, and you can't work out what you did.

You didn't write anything rude. Read it back — every comment is reasonable. That's exactly what makes it hard to fix.

A review comment takes about forty seconds to write. Usually in a fine mood, usually between two other things, and you know exactly how you meant it, because you can hear your own voice saying it.

It's read by someone who just spent three days on this. At the moment they most want it to be finished. And they can't hear your voice. They get the words and nothing else.

So they put a voice back in. Not yours — theirs. Whatever they're feeling about the work right then is the tone your comment arrives in. People are far more confident their tone survives writing than it actually does; there's a well-known study on email where readers picked up the intended tone barely more often than a coin flip. A code review is that, with the added bonus that the reader has just been told what's wrong with their work.

And the first thing text loses isn't friendliness. It's weight.

Out loud, you'd do the weighting without thinking. "Oh — tiny thing, the name's a bit off." "Okay, this one actually matters." Your face and your voice tell them which is which. In a review tool, every comment is the same grey box in the same font. nit: rename to userIds and "this charges the card twice if the job retries" look identical on the screen.

So the author has to guess which ones they're allowed to push back on. And the safe guess, the one that doesn't risk anything, is to do all of them. That's what fourteen "done"s is. Not agreement. Compliance. And compliance carries a little resentment that shows up later, in chat, about something else entirely.

When every comment weighs the same, the only weight left is the count. Fourteen comments reads as a verdict on the whole PR, whatever each one actually says.

There's a second thing text strips, and it's the shape of a question. "Why did you use a map here?" said across a desk with a curious face is a question. Typed, it's a demand to justify yourself. A "why" with no reasoning attached reads as an accusation, and the person who wrote it almost never meant one.

Say how much it all weighs, before anything else.

One line at the top of the review, above every individual comment:

"Looks good overall. One real thing — the retry on line 84. Everything else is small and optional."

That sentence does more work than the other fourteen put together. It gets read first, and it changes how every comment underneath it is read. The author stops scanning for the verdict, because you've already told them what it is.

Then weight each comment in words, at the very start: "Blocking:", "Non-blocking:", "Nit, ignore if you like:". There's a whole convention for this — Conventional Comments — but you don't need the spec. You need the author to be able to answer the one question they're silently asking of every single comment: do I have to? A label that says "no" also gives them permission to disagree with the small stuff without it turning into a fight.

Put your reasoning inside the question.

Not "Why a map here?" Instead:

"I think I'm missing something — is the map because of the lookups? I'd have reached for an array."

Now they're correcting your guess instead of defending their choice. Correcting is easy. Defending is tiring and faintly humiliating, even when you win. And half the time the answer is "yep, the lookups", they type three words, and the thread's over.

After the second reply, stop typing.

Threads escalate on their own in text. Each reply gets a little longer and a little more carefully worded than the last, and careful reads as cold — so both of you feel the other getting frostier while neither of you actually is. By the third round you're not discussing a map anymore. You're discussing who's right.

"This is getting long in text — got ten minutes to talk it through?"

Then, after the call, write one line back in the thread saying what you agreed. The call was for the two of you. The line is for whoever opens this PR in a year.

All of this runs in reverse too, and it's worth knowing when you're the author.

You're supplying the tone. That's not a flaw in you, it's just how text works — but it does mean the harsh version you heard was at least partly your own. Try reading the comment again in the voice of the reviewer on their best day. It's usually closer to what they meant.

And the reply that ends most threads in one round:

"I went this way because the list can get huge. Happy to switch if you still think the array's clearer."

You've given your reason and handed back the decision. On the small stuff that costs you almost nothing, and it makes you easy to review — which matters more than it should, and I'll come back to it. On the thing you genuinely care about, don't hand it back. Say you'd like to keep it, and why. Just pick one or two of those per PR, not fourteen.

Labels don't fix volume. Twenty-five comments that each start with "nit:" still read as twenty-five comments. If most of your review is nits, the fix isn't a better label, it's fewer comments. Gather the small ones into a single comment, or let some of them go. Not every naming preference needs to be in the permanent record.

Softening can bury the thing that matters. This one catches junior reviewers hardest: "Might be worth maybe looking at whether this could possibly retry twice?" The real bug is now wrapped in so much padding that it reads as optional, and it gets merged. If you're junior and reviewing someone senior, you don't need more padding. You need the label and one plain sentence: "Blocking, I think — this runs twice if the job retries. Tell me if I've misread it." The "tell me if I've misread it" is honest cover. The label keeps the weight.

If you're senior, it flips. Your question is an instruction whether you meant it as one or not. "Have you considered a map?" from a staff engineer gets you a map. Softer wording won't change that — only saying it will: "Genuinely optional. I'd be fine either way."

And some teams are blunt, and it's working for them. Padding a comment in a room like that reads as fake, or worse, as manager voice. Before you change how you write, go and read how the reviewers your team actually trusts write. Match them, not me.

The same comment is a different comment depending on who writes it. A lead's "hmm" weighs more than a new joiner's whole paragraph. That's rank, and text doesn't hide it. It amplifies it.

Code review is also a quiet ledger. People who are easy to review tend to get faster reviews with fewer comments. People who fight every thread tend to get slow, thorough reviews for a long time afterwards. Nobody decided that. It just accumulates. It isn't fair, and it's real. The practical version: don't spend yourself on the small threads. Save the argument for the one that matters, and it'll land as the one that matters.

Then there's this year's version. More of the code in a pull request was written with an assistant now, so there's more of it, and reviewers are tired, and tired comments are short, and short comments read as cold. There's also a brand new worst comment available: "Did an AI write this?" Whether it did or not, the author hears "you didn't think about this." If that's what you mean, leave the useful version: "I can't follow why this handles the empty case like this — can you walk me through it?" That's the comment you actually wanted to leave anyway.

Some of how a review lands is simply the other person's day, and you can't touch that. What you can do is make sure it doesn't depend on it.

The next review you leave, write the summary line before you write anything else. One sentence: how many things actually matter, and which one.

"One real thing, the rest are optional."

Then go back through your comments and label each one. If you've left more nits than you'd be comfortable receiving, delete a few.

That's the whole practice. You're not changing what you think about the code. You're putting back the part that text took out.

🚀 Want more like this? Every guide, playground, and quiz lives on bestpractic.org — open it and sign up free so the next one finds you.

Thanks for reading! Let's stay connected:

🤝 Want to make something with us? Write a piece, come on the podcast, or bring an idea that should exist — bestpractic.org/collaborate.

And if this one helped, send it to the person you know who needs it this week. That's what keeps these coming.