The Art of Code Review

Code review is one of those activities that every team does but few teams do well. Done poorly, it becomes a bottleneck — a rubber-stamp process that catches typos but misses design flaws. Done well, it’s the single highest-leverage activity for improving code quality and spreading knowledge across a team.

The Reviewer’s Mindset

The first mistake most reviewers make is treating code review as an audit. They’re looking for things that are wrong. This puts the author on the defensive and turns the review into an adversarial process.

Instead, approach a review with curiosity:

“I don’t understand this — can you help me?” is better than “This is confusing.”
“Have you considered X?” is better than “You should do X.”
“What happens if Y?” is better than “This doesn’t handle Y.”

The goal is a conversation, not a judgment.

What to Look For

I prioritize review feedback in this order:

Correctness: Does this code actually do what it’s supposed to do? Are there edge cases?
Design: Does this fit well into the existing architecture? Will it be easy to modify later?
Clarity: Can I understand this code without the PR description? Will someone reading it in six months?
Performance: Are there obvious performance issues? (Emphasis on “obvious” — premature optimization in review is real.)
Style: Naming, formatting, conventions. This should be the least of your concerns — automate it with linters.

The Author’s Responsibility

Good code review starts before the PR is opened:

Keep PRs small. If your PR is over 400 lines, consider breaking it up. Large PRs get worse reviews — reviewers get fatigued and start skimming.
Write a clear description. What does this change? Why? What alternatives did you consider?
Self-review first. Read through your own diff before requesting review. You’ll catch half the issues yourself.
Provide context. Link to the issue, include screenshots for UI changes, explain non-obvious decisions in comments.

The “Nit” Problem

Every team develops an unspoken hierarchy of review comments. I like to make mine explicit:

Blocker: This must change before merging. Bugs, security issues, architectural problems.
Suggestion: I think this would be better, but it’s your call.
Nit: A minor style preference. Feel free to ignore.
Question: I’m genuinely curious, not suggesting a change.

Prefixing comments with these labels eliminates a huge amount of ambiguity.

Speed Matters

A code review that sits for three days is worse than a mediocre review done in three hours. Context switches are expensive. The author has moved on to other work and now has to re-load the mental context of the original change.

My targets:

First response: Within 4 hours during work hours
Follow-up reviews: Within 2 hours
Small PRs (under 100 lines): Same day, ideally within an hour

If you can’t review promptly, say so. “I won’t be able to review this until tomorrow” is infinitely better than silence.

What I’ve Changed Over the Years

Early in my career, I left detailed comments on everything. Every review had 20+ comments, most of them nits. I thought I was being thorough. I was actually being exhausting.

Now, I focus on the two or three things that matter most. If the design is solid and the code is correct, I approve it — even if I would have written it slightly differently. Different isn’t wrong.

The best code reviews I’ve received were the ones that taught me something new. I try to pay that forward.