Code review as teaching

More than a gate

Code review is usually described as quality control: a second pair of eyes catches bugs before they reach production. It does that, but its larger value is educational. Every review is a conversation about how the team writes software, repeated dozens of times a week. Over a year, those conversations shape the codebase and the people more than any style guide.

Review the right things

Automate what can be automated. Formatting, import order, and simple lint rules should be enforced by tools, not by reviewers. Human attention is better spent on:

• Does this change do what it claims to do?
• What happens in the edge cases: empty input, failure of a dependency, concurrent requests?
• Will the next person to read this understand it?
• Does it fit the existing design, or does it introduce a second way of doing something?

Ask, do not command

"Change this to use a map" teaches nothing. "Would a map make the lookup clearer here? I am thinking of the case where the list grows" invites reasoning and leaves room for the author to know something the reviewer does not. Questions also reduce defensiveness.

Label your comments

Not every comment carries equal weight. Prefixes such as "blocking", "suggestion", and "nit" tell the author what must change before merge and what is optional. Without labels, authors often treat every remark as mandatory and every review as a negotiation.

Explain the why

When pointing out a problem, explain why it is a problem. A reviewer who writes "this will leak a connection if the request times out, because the cleanup only runs on success" has taught something reusable. A reviewer who writes "fix the leak" has only fixed one leak.

Keep changes small

Large pull requests get shallow reviews. Reviewers skim, approve, and hope. Changes under a few hundred lines get careful attention. Encourage authors to split work into small, independently reviewable pieces, even if it takes a little more planning.

Review promptly

A pull request waiting two days for review blocks its author and grows stale as other changes land. Many teams set an expectation of a first response within a few working hours. Fast feedback keeps work flowing and makes small changes practical.

Praise good work

Point out what is done well, specifically. "This test covers the timeout case nicely" reinforces a habit worth keeping. Reviews that contain only criticism teach people to dread them.