Skip to content
Velloreth
Programming 6 min read

A Code Review Checklist That Actually Helps

Good code review catches bugs and shares knowledge without slowing the team down. Learn what to look for, what to skip, and how to give feedback.

By

What code review is for

Code review has two jobs, and teams that optimise for only one get it wrong.

Catch defects. A second pair of eyes finds bugs, security issues, and edge cases the author missed.

Share knowledge. The reviewer learns what changed; the author learns from the feedback. Over time, the team’s shared understanding of the codebase improves.

The second job is easy to forget, and it is why a review that only hunts for bugs is a missed opportunity. It is also why reviews should not be adversarial — the goal is a better codebase, not a verdict on the author.

What to look for

Correctness

The first question: does this do what it claims?

  • Does it handle the edge cases — empty input, null, zero, maximum values?
  • Are the error paths handled, or do they swallow failures?
  • Are the boundary conditions right — off-by-one, inclusive versus exclusive?
  • Does it handle concurrent access if that is possible?
  • Are the tests actually testing the behaviour, or just the happy path?

Security

  • Is user input validated and escaped?
  • Are queries parameterised, or is there string concatenation into SQL?
  • Are secrets kept out of the code and logs?
  • Is authorisation checked, not just authentication?
  • Are dependencies from trusted sources and up to date?

Maintainability

  • Will someone understand this in six months?
  • Are the names accurate and intention-revealing?
  • Is the logic in the right place, or does it belong in another module?
  • Is there duplication that should be extracted — or abstraction that should be inlined?
  • Are the tests readable and focused?

Performance

Only where it matters. Most code is not performance-critical, and premature optimisation is a real cost.

  • Is there an N+1 query?
  • Is there a loop doing linear scans that could be a map lookup?
  • Is anything loading unbounded data into memory?
  • Is there work in a hot path that could be hoisted?

Tests

  • Do the tests cover the new behaviour?
  • Do they cover the failure cases?
  • Are they testing behaviour or implementation details?
  • Would they fail if the code were broken?

What to skip

Formatting. Use a formatter. Prettier, gofmt, rustfmt, and black remove this category entirely.

Style conventions. Use a linter. If a rule matters, encode it in the tool rather than in review comments.

Personal preference. “I would have written it differently” is not a review comment unless you can articulate why the difference matters.

Trivial nits. A typo in a comment is worth mentioning, but not worth blocking on. Mark it as a nit.

Rewriting the whole thing. If you would have designed it differently, that is a design discussion, not a review comment. Raise it separately.

How to give feedback

Comment on the code, not the person

❌ "You forgot to handle the null case."
✅ "This will throw if `user` is null — should we handle that?"

The second version is a question about the code. The first is an accusation.

Ask rather than command

❌ "Use a Map here."
✅ "Would a Map be faster here, since we look up by id in a loop?"

Questions invite discussion and acknowledge that you might be missing context.

Explain the why

❌ "This needs a test."
✅ "This branch handles the expired-token case, which caused a production incident last month — worth a test so it does not regress."

The reasoning makes the request persuasive rather than arbitrary.

Distinguish blocking from optional

Use explicit prefixes so the author knows what matters:

  • blocking: — must be addressed before merge.
  • suggestion: — worth considering, author’s call.
  • nit: — trivial, ignore if you like.
  • question: — I do not understand, please explain.

This convention removes ambiguity and speeds up the author’s response.

Praise good work

If a change is well-tested, clearly structured, or solves a hard problem elegantly, say so. Reviews that only list problems are demoralising, and they miss the chance to reinforce good practice.

How to receive feedback

Assume good intent. The reviewer is trying to help, even if the comment is blunt.

Do not take it personally. The code is not you. A comment on the code is not a comment on your ability.

Ask for clarification rather than defending. “Can you say more about why?” is almost always productive.

Disagree when you have a reason. If you think the suggestion is wrong, explain your reasoning. Reviews are discussions, not verdicts.

Do not resolve comments without addressing them. Either make the change or explain why not.

The size problem

The single biggest factor in review quality is the size of the change.

Diff sizeTypical review quality
Under 200 linesCareful reading, real defects found
200–400 linesGood coverage, some skimming
400–1000 linesSkimming, mostly style comments
Over 1000 linesRubber stamp

Large diffs get approved, not reviewed. The reviewer’s attention is finite, and a 2,000-line change exhausts it before the interesting parts.

The fix is to split. A large feature can be a sequence of small pull requests: the data model, then the service, then the API, then the UI. Each is reviewable, and each can be merged independently.

Practical guidance

  • Keep pull requests under 400 lines where possible.
  • Review within a few hours — delays block the author and encourage bigger changes.
  • Automate formatting and linting so humans review substance.
  • Use explicit prefixes for blocking, suggestion, nit, and question.
  • Comment on the code, not the author.
  • Ask questions rather than issuing commands.
  • Explain the reasoning behind suggestions.
  • Praise good work when you see it.
  • Do not block on preferences.
  • Review your own diff first — you will catch half the issues yourself.

For the related practices, see refactoring basics and writing clean functions. For the team context, technical debt conversation and remote team building for small companies.

Quotable summary

Code review has two jobs: catch defects and share knowledge, and optimising only for the first produces reviews that are slow and demoralising. Focus on correctness, security, and maintainability, and leave formatting and style to automated tools. Comment on the code rather than the author, ask questions rather than issuing commands, and explain the reasoning behind suggestions. Distinguish blocking issues from suggestions and nits with explicit prefixes, so the author knows what must change. Small pull requests get better reviews: under about 400 lines of diff, reviewers read carefully, while a 1,000-line change gets a rubber stamp. Review within a few hours, because delays block the author and encourage larger, riskier changes.

Frequently asked questions

What should I look for in a code review?
Correctness first: does it do what it claims, including edge cases and error paths? Then security, performance where it matters, test coverage, and maintainability. Formatting and style should be handled by automated tools.
How long should a code review take?
Aim to review within a few hours of the request, and keep the review itself under an hour. Long delays block the author and encourage larger, riskier changes. If a review takes longer than an hour, the change is probably too big.
How big should a pull request be?
Under about 400 lines of diff is the common guideline. Beyond that, reviewers skim rather than read, and defect detection drops sharply. Split large changes into a sequence of smaller ones.
Should I comment on style in a code review?
Rarely. Formatting and naming conventions should be enforced by a linter and a formatter, so humans do not spend attention on them. If a style issue is not caught by tooling, consider adding a rule rather than commenting.
How do I give critical feedback without being harsh?
Comment on the code, not the person. Ask questions rather than issuing commands. Explain the reasoning behind a suggestion. Mark non-blocking comments as such, so the author knows what is optional.
What if I disagree with the author?
Discuss the trade-off rather than the preference. If you cannot agree, escalate to a third person or defer to the author if the decision is reversible. Not every disagreement needs to be resolved in the review.