Code Review Best Practices for Authors and Reviewers

Code review is one of the highest-leverage habits a team can have. It catches bugs before users do, spreads knowledge so no one person is a single point of failure, and keeps a codebase consistent. It can also become a slow, frustrating bottleneck full of nitpicks and defensive arguments.

The difference comes down to a few habits on both sides of the pull request.

For authors: make your PR easy to review

Keep it small

Small pull requests get reviewed faster and more thoroughly. A 2,000-line PR gets a skim and an "LGTM." A 150-line PR gets real attention.

If a feature is big, split it: a migration, then the API, then the UI. Feature flags let you merge incomplete work safely. (Branching strategies.)

Write a useful description

Include:

• What changed, in a sentence or two
• Why: the problem, ticket or user need
• How to test it
• Screenshots or recordings for UI changes
• Anything you're unsure about, so reviewers focus there

Review it yourself first

Read your own diff before requesting review. You'll catch leftover debug logs, commented-out code, missing tests and typos, which saves a round trip.

Separate refactoring from behaviour changes

Mixing "rename everything" with "change the pricing logic" hides the important change among hundreds of trivial ones. Do them in separate PRs, or at least separate commits.

Make sure the checks pass

Tests, linting and builds should be green before you ask a human to look. Automation is cheaper than people. (CI with GitHub Actions.)

For reviewers: focus on what matters

Prioritise

Review in roughly this order of importance:

1. Correctness: does it do what it's supposed to? Edge cases, error handling, race conditions.
2. Security: input validation, authorization checks, secrets, injection risks. (Security checklist.)
3. Design: does it fit the architecture? Will it be easy to change later?
4. Tests: are the important paths covered?
5. Readability: names, structure, comments. (Clean code tips.)
6. Style: should be automated by formatters and linters, not debated in review.

Be explicit about severity

Label comments so the author knows what's required:

• "Blocking:" must be fixed before merging.
• "Suggestion:" worth considering, your call.
• "Nit:" trivial, take it or leave it.
• "Question:" I'm trying to understand, not asking for a change.

This prevents authors from treating every comment as a demand, and prevents important issues from getting lost among nitpicks.

Comment on the code, not the person

• Instead of "You didn't handle errors," try "What happens here if the API call fails?"
• Instead of "This is wrong," explain the problem and suggest an alternative.
• Ask questions when you're unsure. The author may know something you don't.

Praise good work

"Nice, this is much clearer than before" costs nothing and makes reviews feel collaborative instead of adversarial.

Review promptly

A PR waiting two days blocks the author and invites merge conflicts. Many teams aim to give a first response within a working day. If you can't review properly, say so, so someone else can.

Don't rewrite it your way

If the code is correct, clear and fits the project's conventions, approve it, even if you'd have written it differently. Preferences aren't defects.

Use a checklist

A short, shared checklist keeps reviews consistent:

• Does it solve the stated problem?
• Are inputs validated and permissions checked?
• Are errors handled and logged appropriately?
• Are there tests for the main paths and important edge cases?
• Any performance concerns (N+1 queries, large loops, missing indexes)?
• Are migrations safe for production? (Migration practices.)
• Is anything confusing that needs a better name or comment?

Resolving disagreements

• Discuss trade-offs with evidence: docs, benchmarks, past incidents.
• Move long threads to a quick call; text is bad at nuance.
• If it's a matter of taste, the author decides. If it's a team convention, write it down so it doesn't come up again.

FAQ

How big should a pull request be?

Small enough to review carefully in one sitting, often a few hundred lines or less. Split large features into smaller, independently reviewable pieces.

What should I look for in a code review?

Correctness, security, design, tests and readability, in that order. Leave formatting and style to automated tools.

How do I give constructive code review feedback?

Focus on the code rather than the person, explain why something matters, label how important each comment is, ask questions when unsure and acknowledge good work.