Code review friction

Does your team agree on what code review is actually for?

Mar 10, 2026

👋 Hey, it’s Stephane. I share lessons, and stories from my journey to help you lead with confidence as an Engineering Manager. To accelerate your growth see: AI Interview Coach | 50 Notion Templates | The EM’s Field Guide | CodeCrafters | Get Hired as an EM | 1:1 Coaching

Paid subscribers get 50 Notion Templates, The EM’s Field Guide, and access to the complete archive. Subscribe now.

Somewhere on your team right now, an engineer is spending five minutes rewriting a two-sentence PR comment. They’re softening it. Adding a “maybe” here, a question mark there. Wondering if “consider” sounds too commanding or too passive. They’ll eventually settle on something that sounds polite but vague enough that the author won’t know whether to act on it.

Meanwhile, another engineer on your team is writing “just do X” and hitting submit without a second thought. Not out of malice - they just want to get through open PRs before standup.

Both of these people think the other one is doing it wrong. And you, as their manager, probably haven’t noticed this is happening at all.

The wording isn’t the problem

When code review friction comes up, the conversation almost always goes to individual communication style. Engineer A is too blunt. Engineer B hedges so much that nobody knows what they actually want changed. The proposed fix is usually some variation of “be more polite” or “be more direct”, depending on which camp you’re in.

This framing misses the point entirely.

The reason PR comments cause friction isn’t that people choose the wrong words. It’s that your team has never explicitly agreed on what code review is for, what different types of comments mean, and what happens when two people disagree. Without that shared understanding, every comment is an ambiguity to be interpreted through whatever emotional filter the reader happens to be running that day.

I realised this while managing a team where a senior engineer’s reviews kept generating complaints. His comments were technically accurate and reasonably worded - like “This approach won’t scale past a few hundred concurrent users. Use X pattern instead.” Factually correct. Not personal. Still, two of his colleagues found him “aggressive”.

The problem wasn’t his tone. The problem was that the team had no shared language for “this is a blocking concern” versus “this is a preference”. Every comment carried the same implicit weight, so every comment felt like an order.

What you actually need to build

Instead of asking individuals to calibrate their wording, give the team a shared framework. This doesn’t need to be elaborate. In my experience, you need agreement on three things:

1. Severity signals

The simplest version is blocking versus non-blocking. If your team can’t tell from a comment whether it needs to be addressed before merge, you have a broken system. Some teams use prefixes like nit: or blocker:. Some use emoji. The specific mechanism matters far less than the consistency. Pick something, agree it with the team, and make sure to use it for a few weeks until it becomes habit.

One thing I’ve seen work well: if none of your comments are blocking, approve the PR when you submit the review. This single practice eliminates an enormous amount of ambiguity. Discuss ideas like that with your team!

2. What’s in scope

Does your team review for correctness only? Architecture? Style? Naming? Test coverage? If you haven’t answered this explicitly, your engineers are each reviewing against their own internal checklist, and those checklists don’t match. This is where “nitpicky” reviews come from - one person’s essential feedback is another person’s waste of time, and neither of them is wrong given the absence of a shared standard.

In my opinion, style concerns should mostly be handled by linters and formatters before a human ever sees the code. Every opinion you can automate is a potential argument you’ve prevented.

3. The escalation path

What happens when the reviewer and the author disagree? You certainly don’t want PR comment threads spiral into twelve-message arguments where neither person will budge because there’s no defined way to resolve the deadlock. As a manager, you need to make it clear: if two or three comments can’t resolve it, get on a call. If a call can’t resolve it, bring in a third person or escalate to the tech lead.

Written disagreements in PR comments compound in the worst possible way. Each response adds a layer of interpretation and defensiveness. The same conversation that could take three minutes on a call takes three days in a comment thread and leaves both people irritated.

If you’re enjoying this article, consider subscribing to get:

✉️ Free: 1 original post every Tuesday, my favourite posts of the week every Sunday + 10 Notion Templates for Engineering Managers
🔒 Paid: Full archive + 50+ EM templates & playbooks + The EM Field Guide

The thing nobody wants to admit about PR comments

Code review is often the only place where engineers give each other direct technical feedback. There’s no design review. No pairing. No architecture discussion before the code is written. The PR becomes the first time anyone other than the author sees the approach - and if the approach is wrong, the feedback arrives after hours of work are already invested.

That’s a recipe for defensiveness no matter how carefully you word your comments.

If your team keeps having tense reviews about fundamental design choices, that’s a signal that you need to move those conversations earlier. A thirty-minute design discussion before someone starts building is worth more than a hundred carefully worded PR comments after they’ve finished.

If your architectural decisions are caught at the PR stage, by that point, the author has spent days on the implementation. Telling someone their approach needs a rethink, no matter how gently you phrase it, is going to sting. The emotional cost of that feedback is directly proportional to the sunk cost of the work. Move the conversation upstream and you deflate most of the tension before it exists.

Your actual job here

You can share articles about conventional comments and communication frameworks. You can tell your engineers to use “consider” instead of “do”. None of that is harmful, and some of it might help a bit.

But the lasting fix is structural, not linguistic. Your job as an engineering manager is to create the conditions where code review works well, not to personally wordsmith every interaction between your reports.

That means building explicit norms, automating the stuff that doesn’t need human judgment, and making sure big decisions happen before the PR.

The teams that do code review well aren’t teams full of people who write perfectly calibrated comments. They’re teams where everyone knows what kind of feedback to expect, what requires action, and what to do when they disagree. The individual wording matters a lot less when the system around it is clear.