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 Velloreth
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 size | Typical review quality |
|---|---|
| Under 200 lines | Careful reading, real defects found |
| 200–400 lines | Good coverage, some skimming |
| 400–1000 lines | Skimming, mostly style comments |
| Over 1000 lines | Rubber 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.