Writing Code Reviews That Actually Help People Improve

Code reviews serve three purposes: catching bugs before they reach production, sharing knowledge across the team, and maintaining code quality standards. Most reviews accomplish none of these because they focus on the wrong things — style preferences, naming bikeshedding, and minor formatting issues.

Here is how to write reviews that catch real issues and help your colleagues improve.

The Priority Framework

When reviewing code, check for issues in this order:

Priority 1 — Correctness: does the code do what it claims to do? Are there bugs, edge cases, or logic errors? These are the most important issues because they affect users.

Priority 2 — Security: does the code introduce vulnerabilities? SQL injection, XSS, authentication bypasses, insecure data handling? These are critical because they affect all users.

Priority 3 — Architecture: does the design fit the system? Will it create maintenance problems? Is it in the right layer? Does it follow established patterns? These matter for long-term health.

Priority 4 — Performance: will this code be slow under realistic conditions? N+1 queries, unnecessary re-renders, large payloads? Only matters if the code is on a hot path.

Priority 5 — Style and readability: naming, formatting, code organization. Important but lowest priority. Often handled by automated linters.

What to Comment On

Comment on issues that: a linter cannot catch (logic errors, missing edge cases, architectural concerns), might not be obvious to the author (context they might lack about how the system works), would cause problems in production (bugs, performance, security), or represent a learning opportunity (patterns the author might not know).

Do NOT comment on: anything a linter or formatter handles (let tools enforce style), personal preferences that do not affect quality ("I would name this differently" — unless the name is genuinely confusing), and things that are fine but you would do differently.

How to Write Helpful Comments

Bad comment: "This is wrong." — provides no information about what is wrong or how to fix it.

Good comment: "This query runs inside a loop (line 34-38), which creates an N+1 query problem. If there are 100 tools, this executes 100 separate database queries. Consider using a single query with a WHERE IN clause or Prisma's include to eager-load the data." — explains the problem, the impact, and the solution.

Structure for effective comments: what the issue is (specific description), why it matters (impact on users, performance, or maintenance), and how to fix it (suggestion or direction).

Praise What Is Good

Reviews should not be exclusively negative. When the author does something well — clean abstraction, thoughtful error handling, good test coverage, elegant solution — say so.

"Nice approach using a discriminated union here — it makes the impossible states unrepresentable. I will use this pattern for similar cases." This reinforces good patterns and makes reviews feel collaborative rather than adversarial.

The Question Technique

Instead of directive comments ("change this to X"), ask questions that help the author discover the issue themselves:

"What happens if userInput is null here?" — the author checks and realizes they need null handling.

"Have you considered what this does under concurrent requests?" — the author thinks about race conditions they had not considered.

"Is this query performance acceptable for the tools listing page that shows 600 items?" — the author checks the query execution and realizes it needs optimization.

Questions teach. Directives fix one instance. The developer who answers "what happens if this is null?" will think about null cases in their next PR. The developer who is told "add a null check" will only add it where you pointed.

Handling Disagreements

When you and the author disagree on approach:

Is it a clear bug or security issue? Insist politely. These are non-negotiable.

Is it an architectural preference? Discuss the trade-offs. "I see two approaches here — yours and [alternative]. The trade-offs are: yours is simpler now but harder to extend. The alternative is more complex now but handles future requirements." Then decide together or defer to the author (it is their code).

Is it a style preference? Let it go. If both approaches work correctly and are readable, the author's preference wins. You can propose a linting rule if you feel strongly about consistency.

Review Speed Matters

Slow reviews (taking 2+ days) block progress and frustrate authors. Fast reviews (same day or next morning) maintain team velocity and signal that you respect their time.

My practice: review PRs within 4 hours during working hours. A quick "I will review this by end of day" message if I cannot review immediately. Never let a PR wait more than 24 hours without at least an initial look.

For large PRs (500+ lines): provide an initial pass focusing on architecture within a few hours, then a detailed review of implementation within a day.

Reviewing Large PRs

Large PRs are harder to review thoroughly. Strategies: review commit-by-commit if the author structured commits logically, focus first on the overall approach (is the architecture sound?) before diving into line-by-line details, and ask the author to highlight areas they are uncertain about.

Prevention: encourage small, focused PRs. A 100-line PR gets a thorough review. A 1000-line PR gets a surface-level scan. The quality of feedback is inversely proportional to PR size.

The Cultural Impact

Consistently helpful reviews create a culture where: people look forward to feedback (because it genuinely improves their code), quality standards are shared (everyone learns from everyone's reviews), bugs are caught before production (the team gets better at prevention over time), and junior developers grow faster (regular, constructive feedback accelerates learning).

The opposite — reviews that are nitpicky, slow, or dismissive — creates: review avoidance (developers dread opening PRs), defensive coding (optimizing for passing review rather than quality), and knowledge silos (nobody reviews because it is unpleasant).

Making Time for Reviews

Treat reviews as first-class work. Block time daily for reviews (30-60 minutes). Do not review at the end of the day when you are tired — review when you have cognitive energy.

Reviews are not interruptions to "real work." They ARE real work — they improve code quality, share knowledge, and prevent production issues. A team that skips reviews ships faster in the short term and slower in the long term (as bugs and tech debt accumulate).