Engineering practice
Notes on writing code reviews people actually read
July 2, 2026 · 3 min read
The problem with most reviews
A review that's a wall of nitpicks — semicolons, naming, formatting a linter should have caught — trains people to skim your comments instead of reading them. By the time you leave a comment that actually matters, it's buried in the same tone as the trivial ones.
Lead with intent, not nitpicks
Say what you think the code is trying to do, and whether it does that safely — for the reader six months from now, not just for this PR. Everything else is secondary. If the intent and the safety are solid, most of the smaller stuff can be a suggestion, not a blocker.
Disagree in a way that invites a reply
Phrase pushback as a question you'd genuinely want answered — "what happens if this runs twice?" — rather than a verdict. It gets you the same outcome when you're right, and it gets you corrected quickly when you're not, instead of the author quietly resenting a comment they disagreed with but didn't feel safe contesting.
Got a project or idea you want to talk through?
Get in touchNew explainers, straight to your inbox
One email whenever a new concept goes up. No spam, unsubscribe anytime.