How to Do Code Review That Actually Helps

Step 1: Understand the Goal of Code Review

Code review is not about proving you're smart. It serves three purposes:

1. Catch bugs before they reach production
2. Spread knowledge so the team understands the codebase
3. Maintain standards so the code stays consistent and readable

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:

• What problem does this PR solve? (Read the description first.)
• Is this the right approach? (Architecture before line-level.)
• Does this have tests? (If not, that's your first comment.)

Step 2: Review in Layers

Don't try to catch everything in one pass. Review in three layers, from big to small:

Layer 1: Architecture (2 minutes)

• Does this change belong in this file/module?
• Does it follow existing patterns or introduce a new one?
• Are there any new dependencies? Are they justified?
• Could this be simpler?

Layer 2: Logic (10 minutes)

• Are the edge cases handled? (null, empty, zero, negative, very large)
• Is the error handling correct? (Does every catch block do something useful?)
• Are there race conditions in async code?
• Does the data flow make sense?

Layer 3: Details (5 minutes)

• Naming: are variables and functions descriptive?
• Types: are they specific enough? Any any types?
• Style: does it match the rest of the codebase?
• Comments: is anything confusing that needs explanation?

This layered approach prevents you from bikeshedding on variable names while missing a security vulnerability.

Step 3: Write Comments That Help

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.

Step 4: Know What to Approve, Request Changes, or Block

Not every issue is a blocker. Learn to triage:

Approve immediately if:

• The logic is correct
• It has appropriate error handling
• Tests pass (or it's a change that doesn't need tests, like copy)
• Minor nits can be addressed in a follow-up

Request changes if:

• There's a bug that will affect users
• Error handling is missing for a failure path that will happen in production
• The code contradicts the team's agreed patterns
• There are no tests for non-trivial logic

Block if:

• Security vulnerability (SQL injection, exposed secrets, broken auth)
• Data loss risk (destructive migration without backup, overwriting user data)
• Breaking change to a public API without versioning

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.

Step 5: Make Your PRs Easy to Review

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:

• Refactor PR — Move and rename things, no behavior change
• Feature PR — Add the new behavior on top of the refactor
• Test PR — Add comprehensive tests for the new feature

Make the diff reviewable:

• Separate formatting changes from logic changes (don't reformat a file in the same PR that adds a feature)
• Use descriptive commit messages so reviewers can follow the story
• Respond to every review comment, even if it's just "Done" or "Good point, fixed"

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.