The comment that costs you a teammate
Every senior engineer has seen — or written — the code review comment that pushed a junior engineer to start polishing their résumé. It is rarely rude. It is almost never factually wrong. It is usually a confident one-liner that treats the author's decision as obviously incorrect, delivered without the context that would make the correction land as a gift rather than a reprimand.
The fix is not to be gentler. The fix is to be more specific.
Review comments that work
A review comment that builds trust almost always contains three things:
- What you would change. Be concrete. 'Consider extracting this' is useless; 'Consider extracting lines 42–58 into a
validateRangehelper so the boundary logic is reusable' is actionable. - Why it matters. Not 'this is cleaner' — that is an assertion, not an argument. The actual reason: 'Because the same range check appears in the webhook handler and they will drift.'
- What you are unsure about. Reviewers who never express uncertainty teach their team that certainty is the only acceptable register. The best reviewers flag their own guesses: 'I think this is a bug, but I might be missing something — walk me through what happens when the queue is empty?'
This template — change, reason, uncertainty — takes ten seconds longer to write. It costs nothing and prevents most of the review-review debates that waste sprint time.
Nits, blockers, and the middle ground
Every team should agree on a convention that separates blocking feedback from preferences. The standard we recommend:
- Blocking: 'This is wrong and must change before merge.' Prefix with
blocking:or use the 'Request Changes' button. - Suggestion: 'Here is a better way, but I will approve either version.' Prefix with
suggestion:. - Nit: 'Cosmetic, feel free to ignore.' Prefix with
nit:. - Question: 'I want to understand before I can review.' Prefix with
question:.
Teams without this vocabulary end up relitigating whether every comment blocks the merge. Ten minutes of convention setup saves hundreds of hours per year.
The senior engineer's real job in a review
The mistake most senior engineers make is reviewing for correctness only. Correctness is table stakes. The actual job in a review is:
- Flag architectural drift. This PR is correct in isolation, but does it push the system in a direction you do not want over time?
- Name the invariant. When you spot a subtle bug, articulate the invariant that was violated. That invariant becomes the mental model the junior engineer carries forward.
- Acknowledge the hard parts. If the author solved something genuinely tricky, say so. Praise in reviews is not a participation trophy — it is a signal about what work the team values.
- Teach the taste. Explain why a pattern is good or bad, not just that it is. A review that only says 'use the
Resulttype here' is worth a tenth of a review that explains whatResultbuys you and when to reach for it.
The hard truth
Review culture is the single biggest predictor of engineering culture because it is where the team's standards become concrete and public. Sloppy reviews produce sloppy codebases. Mean reviews produce attrition. The middle path — specific, curious, and explicit about uncertainty — is not slower. It is the only one that compounds.
