Almost every engineering team does code review, and many teams do it badly. Reviews turn into a bottleneck, a stream of nitpicks, or a rubber stamp nobody reads. When they work, they catch bugs before production and teach people how the codebase fits together.
Whoever leads the codebase sets the tone through the reviews they write and the way they take feedback on their own code. This is the process I follow.
Why Code Reviews Matter
A good review process does four things:
- Finds defects early, when they're cheapest to fix.
- Spreads knowledge, so more than one person understands each part of the system.
- Keeps the codebase consistent in structure, naming and patterns.
- Helps developers grow. Newer engineers in particular learn a lot about how the team works from reviews.
If you keep all four in mind, reviews don't shrink into "does it compile and look tidy".
Step 1: Make Pull Requests Easy to Review
Good reviews start with the author. Ask your team to follow a few simple rules:
- Keep PRs small. Aim for a few hundred lines of meaningful change at most. Large PRs tend to get skimmed.
- Give each PR one purpose. Don't mix a refactor, a bug fix and a new feature.
- Explain why. The description should say what problem this solves, how, and how it was tested.
- Point out the risky parts. "Please look closely at the retry logic in
payments.ts" saves the reviewer time.
A simple template in the repository helps:
## What and why
<!-- What does this change do, and why is it needed? -->
## How
<!-- Key implementation decisions and trade-offs -->
## Testing
<!-- How was this tested? Screenshots for UI changes -->
## Risks / things to check
<!-- Anything the reviewer should look at closely -->
Step 2: Review in the Right Order
I start broad and finish narrow. There's no reason to flag typos before you know the approach makes sense.
- Does it solve the right problem? Re-read the ticket or requirement first.
- Is the approach sound? Architecture, data model, API design, edge cases, failure modes.
- Is it correct? Logic, error handling, concurrency, security, performance hot spots.
- Is it tested? Do the tests cover the important paths, including failures?
- Is it readable and maintainable? Naming, structure, duplication, comments where the code isn't obvious.
If step 1 or 2 has a problem, say so and stop there. Code that's going to be rewritten doesn't need line-by-line comments.
Tip
Let tools handle formatting and style. A linter and formatter in CI (ESLint, Prettier and so on) take care of most style comments, so reviewers can spend their time on the logic.
Step 3: Label Your Comments
Some comments matter more than others, and the author can't tell which unless you say so. I prefix each comment:
| Prefix | Meaning |
|---|---|
| blocking: | Must be fixed before merging (a bug, a security issue, broken behavior) |
| suggestion: | A better approach worth considering; the author decides |
| question: | You don't understand something; may or may not lead to a change |
| nit: | Minor style or naming preference; fine to ignore |
| praise: | Something done well, worth calling out |
With labels, authors stop treating every nit as a demand, and there's less arguing over small things.
Step 4: Write Comments That Teach
A comment can point at the right problem and still be unhelpful because it gives no context. Compare:
"This is wrong."
with:
"blocking: if
fetchUserthrows here, the transaction stays open and holds the lock. Could we wrap it intry/finallyand roll back on error?"
Good review comments:
- Explain why the change is needed.
- Suggest a concrete fix or ask a guiding question.
- Talk about the code rather than the person: "This function does X" instead of "you did X".
- Point out good work. A quick "nice, this is much cleaner" makes critical feedback easier to hear.
Note
For developers who are new to the codebase, a guiding question ("What happens if the list is empty?") often teaches more than handing over the answer. Save direct fixes for when time is tight.
Step 5: Keep Reviews Fast
Slow reviews cost a team more than people notice. A PR waiting two days blocks the author, invites merge conflicts and pushes people toward bigger PRs next time.
Agree on a team expectation, such as a first response within half a working day, and make it easy to meet:
- Review in batches a few times a day rather than whenever a notification arrives.
- If you can't do a full review soon, say so and suggest someone else.
- For large changes, go through the review together on a call instead of trading dozens of comments.
- Approve with minor comments when the remaining issues are nits the author can fix without another round.
Step 6: Be a Good Author Too
Your team also learns from how you handle comments on your own PRs:
- Assume good intent. The reviewer is trying to improve the code.
- Reply to every comment, even if only "done" or "good point, will follow up in a separate PR".
- Push back with reasons when you disagree, and accept that sometimes the team's convention wins.
- Move long debates to a call. After three rounds of back-and-forth in comments, a five-minute conversation is usually faster.
Code Review Checklist
Before approving, ask yourself:
- Does this solve the actual problem described in the ticket?
- Is the approach reasonable, and are trade-offs explained?
- Are edge cases and failures handled (empty input, timeouts, retries, permissions)?
- Are there tests for the important paths?
- Is anything security-sensitive (auth, input validation, secrets, data exposure)?
- Will someone new to this code understand it in six months?
- Are my comments labeled, explained and respectful?



