Why Most Code Reviews Miss the Mark

A pull request sits open for three days. The author pings twice. The reviewer finally looks, leaves two comments ("this is confusing" and "can you refactor this?") and approves.

The author doesn't know what to do with "this is confusing." They push a minor name change, the reviewer approves, and the confusing code ships.

That's not a code review. That's a rubber stamp with friction.

Good code review is a skill. It's learnable. And it's one of the highest-leverage things a senior engineer can develop, because every person you review is learning from your feedback.

The Three Jobs of a Code Review

Before you start reading a diff, get clear on what you're actually doing:

  1. Catch bugs and correctness issues: the obvious one
  2. Maintain the codebase's long-term health: naming, architecture, test coverage
  3. Transfer knowledge: teach the author something they didn't know

Most reviewers focus entirely on #1. The best reviewers do all three.

Make Feedback Actionable

The worst code review comments are vague reactions:

  • "This seems off"
  • "I'm not sure about this approach"
  • "This feels wrong"

A useful comment answers three questions:

  1. What is the problem?
  2. Why is it a problem?
  3. What should be done instead?

Vague: "This naming is confusing."

Actionable: "The variable data is used to mean two different things in this function: the raw API response and the parsed result. Consider rawResponse and parsedUser to make the distinction clear. It'll help whoever debugs this at 2am."

The extra two sentences are the entire value.

Distinguish Blocking from Non-Blocking

Not all feedback is equal. Make it explicit:

  • Must fix: A bug, a security issue, a correctness problem. The PR shouldn't merge without addressing it.
  • Should fix: A meaningful improvement that's worth doing now.
  • Nit: A minor style preference. The author can take it or leave it.
  • Question: You genuinely don't understand something and need clarification.

Prefix your comments accordingly. nit:, question:, blocking:. This alone reduces the anxiety around code review by 50%.

The Tone Problem

Code review has a tone problem. Written text is stripped of the warmth that makes in-person feedback land well.

A comment that sounds neutral in your head reads as critical to the author. The author spent two days on this. They're emotionally invested. They're reading every comment looking for approval or rejection.

A few things that help:

Be specific about the code, not the person. "This function is hard to follow" not "you wrote a hard-to-follow function."

Explain why you care. "I'd prefer the values inlined here because it makes the default behavior visible at a glance, which helps during onboarding."

Acknowledge tradeoffs. "Either approach works here. I slightly prefer X because Y, but it's your call."

Praise what's working. You don't have to manufacture compliments. But when you see something genuinely well done, say so. "This test setup is clean. I'm going to steal this pattern."

When to Approve with Comments

Most code reviews should end with "approve with minor nits" or "approve with one required change," not "changes requested" on a laundry list.

If you have six nits, approve and note them. Let the author decide which are worth fixing. Trust them.

Reserve "changes requested" for blockers. If it has a bug or a security issue, block it. If you just have opinions, say so, then get out of the way.

The Meta-Skill

The best code reviewers I've worked with have one thing in common: they make authors feel smarter after the review than before it.

They leave comments that teach. They ask questions that prompt the author to discover better solutions themselves. They surface things the author didn't see, not to show off, but because they genuinely want the code and the person to be better.

That's the job.