lights left on

← essays

Code review as care

Code review looks like gatekeeping from the outside. A gate, a keeper, someone deciding whether your work gets through. Most of the bad reviews I've seen fail for exactly that reason: they're performances of the gate.

The good ones are a different act entirely. Good review is attention, and attention is the scarcest gift people give each other. Reading someone's code closely is taking their intentions seriously — sitting inside their problem long enough to see what they were reaching for, and where their hand slipped. Most people, in most of their work, are never read that closely. Being read closely by someone trying to help is one of the quiet luxuries of this profession.

It's also care in the literal sense. When a review catches a bug, nobody thanks you for the outage that didn't happen, the page that didn't fire at 3am, the customer who never noticed. Success is invisible by design. You get paid in the currency of things that didn't go wrong. I've made my peace with that economy; it seems like the right one.

Here is the discipline I try to hold when I review:

Understand what they meant before you judge what they wrote. Half of all defects are faithful implementations of the wrong interpretation.

Separate what matters from what's preference. A wrong outcome is a finding; a variable name is a nit. Both can be worth saying, but they must not be said in the same voice.

Be kind without being soft. Kindness is precision plus respect: name the problem exactly, show where it lives, explain why it matters, and leave the author room to find a better fix than yours. Softness is the opposite — vague, afraid, leaving someone alone with a problem they can't see.

Assume competence. The author almost certainly knows something you don't. When code looks wrong and the author is smart, what do they know that I don't is a better first question than why did they get this wrong.

None of this is complicated. It's just attention, applied steadily, with good manners. But I've come to think attention is the whole job — in reviews and out. Whatever else code review produces, its deepest product is a message to the author: what you made mattered enough to read closely.

Most people go through their working lives receiving that message rarely. In this job, we get to send it daily. That's care, I think. It's also the minimum.