Loading
A practical guide to reviewing code for correctness, clarity, and maintainability — with actionable feedback patterns that make teams better.
Code review is not about proving you're smart. It serves three purposes:
A good review takes 15-30 minutes. If you're spending more than an hour, the PR is too large — ask the author to split it.
Before you start reading code, answer these questions:
Don't try to catch everything in one pass. Review in three layers, from big to small:
Layer 1: Architecture (2 minutes)
Layer 2: Logic (10 minutes)
Layer 3: Details (5 minutes)
any types?This layered approach prevents you from bikeshedding on variable names while missing a security vulnerability.
The difference between a helpful review and a demoralizing one is how you phrase feedback.
Bad comments:
Good comments:
Comment patterns:
| Prefix | Meaning | | --------------- | ------------------------------------------- | | Bug: | This will cause incorrect behavior | | Nit: | Minor style issue, non-blocking | | Question: | I don't understand something, help me learn | | Suggestion: | Alternative approach, take it or leave it | | Blocker: | Must fix before merge |
Always explain why something is a problem and what you'd suggest instead. "This is wrong" teaches nothing. "This will return stale data because the cache isn't invalidated after the write — add revalidatePath() after the mutation" teaches everything.
Not every issue is a blocker. Learn to triage:
Approve immediately if:
Request changes if:
Block if:
When you request changes, be specific about what needs to change. "Please add error handling" is vague. "The fetchUser call on line 42 needs a try/catch — if the API is down, this will crash the page" is actionable.
Good reviewing starts with good PRs. If you want fast, thorough reviews, make the reviewer's job easy:
PR description template:
Size matters. Research consistently shows that review quality drops sharply after 400 lines of changes. Small PRs get reviewed faster and more thoroughly. If your change is large, split it:
Make the diff reviewable:
The best teams treat code review as a conversation, not an inspection. Both author and reviewer learn something. Both leave the codebase better than they found it.
"This is wrong."
"Why would you do it this way?"
"This won't work.""This will throw if `items` is empty — we should add a guard:
if (items.length === 0) return [];"
"Nit: `data` is pretty generic here. `lessonProgress` would make
this easier to follow when reading the function."
"Question: I see we're fetching all users and filtering client-side.
Was there a reason not to filter in the query? The table could
grow to 100k+ rows."## What
One sentence describing the change.
## Why
The problem this solves or the feature this adds.
## How
Brief explanation of the approach, especially non-obvious decisions.
## Testing
How you verified this works. Screenshots for UI changes.