What three years of code review taught me about communication

I used to think the point of a code review was to find bugs.

Three years and a few hundred reviews later, I think that's maybe twenty percent of it. The rest is communication — making sure the person on the other side of the diff understands not just what to change but why it matters, and feeling respected enough to want to do it.

This sounds obvious written out. It wasn't obvious to me when I started.

The review that changed how I think about this

Early in my time working on large-scale web properties, I submitted a PR that I was proud of. Clean refactor, better performance, reduced bundle size. The review I got back was technically accurate and also completely demoralising.

Every comment was phrased as a correction. This is wrong. This should be X. Why did you do it this way? No explanation of why, no acknowledgement of what was good, no sense that the reviewer had considered that I might have had reasons for my choices.

I made the changes. I didn't learn anything. I was more careful about what I submitted to that reviewer in future — not more careful in a good way, careful in a defensive way.

That review stuck with me. When I started giving more reviews myself, I kept asking: what kind of reviewer do I want to be?

What actually makes feedback land

The difference between feedback that improves the code and feedback that just creates friction isn't the technical content. It's the framing.

Explain the why, always. "Extract this into a separate component" is a command. "Extracting this into a separate component would let us reuse it in the events page we're building next quarter — worth considering?" is an invitation. Same suggestion, completely different reception.

Ask questions more than you make declarations. "Is there a reason this runs on every render rather than being memoised?" opens a conversation. The person might have a good reason. They might not. Either way you find out, and either way they don't feel accused of something.

Acknowledge what's good. Not performatively — engineers see through "great job!" on every PR. But when something is genuinely clean or clever, say so specifically. "I like how you handled the edge case on line 34, hadn't thought of doing it that way." It takes ten seconds and it changes the whole tone of the review.

Separate blocking concerns from preferences. I mark my comments explicitly: blocking (this needs to change before merge), suggestion (I'd do it differently but either works), nit (genuinely doesn't matter, just noticing). Mixing these is how you end up in a review that takes three days over a disagreement about variable naming while a real bug sits unaddressed.

What I've learned about receiving reviews

Giving better reviews got easier once I got better at receiving them.

The thing I had to unlearn: a comment on my code is not a comment on me. This is easy to say and genuinely hard to feel, especially on work you care about. I still have to remind myself sometimes.

What helps: read every comment once, close the PR, come back in an hour. The comments that felt like attacks usually just feel like feedback after you've had some distance. The ones that still feel wrong after an hour are usually worth a conversation.

Ask for the reasoning when it's missing. "Can you help me understand what the concern is here?" is not a defensive response, it's a professional one. Some of the best technical conversations I've had started with a reviewer explaining something I'd pushed back on, and me realising they were right for a reason I hadn't seen.

The thing I think about now when I open a diff

The person who wrote this code was trying to solve a real problem. They made decisions under time pressure and uncertainty, probably without knowing everything I know now reading the result. My job isn't to find everything wrong with their solution — it's to help them make it better while leaving them more confident, not less.

That's a higher bar than "find the bugs". It's also more interesting.