In many teams, code review is a checkpoint: a change waits in a queue, someone scans it for typos, and it's approved. That catches little and frustrates everyone. The most valuable reviews look past the syntax to the decisions behind the change.
Review the approach before the details
The most expensive review comment is the one that arrives after the work is finished: “this should have been designed differently.” Short design notes or draft pull requests shared early let reviewers weigh in while changing direction is still cheap.
Keep changes small enough to understand
A reviewer can reason carefully about a focused change. A two-thousand-line pull request gets skimmed. Breaking work into small, self-contained steps makes reviews faster, more thorough and less stressful for everyone involved.
Let machines check what machines can
Formatting, linting, type checks and tests should run automatically before a person looks at the change. That frees reviewers to focus on what tools can't judge: clarity, the correctness of business logic, edge cases and whether the change fits the system.
Good reviews ask “why?” as often as “what?” — and the answers usually belong in the code or its documentation.
Write comments that teach
Explain the reasoning behind a suggestion, distinguish blocking issues from preferences, and point to examples. A comment that teaches improves the next change as much as this one. Call out good decisions too — it makes clear which patterns to repeat.
- Say whether a comment is blocking or optional.
- Suggest rather than command — and offer an alternative.
- Move long threads to a quick call, then record the outcome.