Writing Code Reviews That Don't Annoy Your Teammates
You can learn a lot about a team from its pull requests. Not from the code — from the comments. Whether feedback reads as curiosity or as gatekeeping, whether reviews land in an hour or in three days, whether the same two people do all the reviewing while everyone else rubber-stamps.
I've spent years on both sides of the review box, and a few more reading review threads as a team lead when they turn sour. The pattern is almost always the same: nobody was wrong about the code. Someone was just careless with the humans. Here's what I try to hold myself and my teams to.
Comment on the code, not the coder
"This function is hard to follow" and "you made this hard to follow" contain the same information — only one of them starts an argument. Keep the subject of every sentence the code, and phrase uncertainty as a genuine question: "What happens here if the list is empty?" beats "This breaks on empty lists" — especially when you're not sure it does.
Questions also leave room for the answer you didn't expect. Half the time my sharpest review catch turns out to be a constraint I didn't know about. Asking instead of asserting means being wrong costs nothing.
Separate blocking from preference
The fastest way to exhaust an author is twenty comments of equal apparent weight, where three are real problems and seventeen are taste. Label them. A simple "nit:" prefix on the take-it-or-leave-it comments, and an explicit "this one I'd consider blocking" on the ones that matter, lets the author triage instead of treating every note as a demand.
And if a style rule matters enough to enforce in every review, it matters enough to automate. Formatting and lint arguments belong in the linter config, argued once — not relitigated across a hundred pull requests.
A review is two people improving the thing together. The moment it becomes a gate to get past, everyone starts optimizing for the gate instead of the thing.
Latency is part of the feedback
A thorough review that arrives three days late is worse than a decent one within the hour. The author has moved on, the context is cold, and the branch is rotting. Reviews are not interruptions to real work — on a team, they are the real work. I try to treat review requests like messages from a teammate who is blocked, because that's what they are.
Say what's good, specifically
"LGTM" is approval, not feedback. When someone handles an edge case elegantly or finally untangles a function everyone feared, say so, on the line. Specific praise teaches as much as specific criticism — it tells the team what good looks like here — and it makes the hard comments easier to hear when they come.
Authors: make your work reviewable
Half of annoying reviews are downstream of unreviewable pull requests. Keep diffs small enough to hold in one head. Write a description that says what changed and why, not just a ticket link. Review your own diff first — you'll catch the debug logging and the leftover TODO before anyone else has to. And when a change looks strange without context, annotate it yourself before the reviewer has to ask.
None of this slows a team down. It's what fast actually looks like over more than one sprint: small diffs, quick turnarounds, comments that are easy to act on, and nobody bracing themselves before opening their review tab. The code gets better either way — the difference is whether the people do too.