Code Review That Actually Improves Quality

A code review is a conversation about a change, held before the change reaches users. Done well, it catches defects, spreads context and raises the quality of the whole codebase. Done badly, it becomes a queue where work waits for a senior person, comments focus on formatting and the author learns to hide rather than improve.

Make the pull request easy to review

The author controls most of the review experience. A good pull request has a short title, a description that explains why the change exists, a link to the issue and a note on how it was tested. It is small enough to read in one sitting, and it does not mix a refactor with a behaviour change. If it does, split it.

Screenshots and recordings are worth more than paragraphs for anything visual. For a bug fix, include the failing case and the result after the fix. For a migration, include the rollback plan. The reviewer should not have to reconstruct the context from the diff alone.

Review the code as if the author is competent and the change is risky. Both assumptions are usually true.

What to comment on, and what to leave

Comment on correctness, security, data handling, error paths, naming that will confuse the next reader, and tests that do not test the behaviour. Leave out personal style preferences that a formatter can settle. If the team cannot agree on formatting, automate it and remove the argument from review entirely.

Distinguish blocking comments from suggestions. A comment that must be fixed before merge should say so; a preference should say non-blocking. Without that signal, authors either treat every note as a demand or ignore the important one along with the trivial ones.

A checklist that fits on one page

A checklist is useful when it is short enough to remember. Ours covers the questions that catch the expensive mistakes, and it is deliberately not a substitute for reading the change. Run through it once, then read the diff properly.

Does the change do what the description says, and only that? Are error paths handled, not just the happy path? Is user input validated and output escaped where needed? Are permissions checked on the server, not just hidden in the UI? Do the tests fail if the behaviour regresses? Is there a rollback plan for anything irreversible? For security-sensitive changes, add a second reviewer with the relevant context.

Review speed and team culture

A review that sits for two days costs more than a slow review that happens today. Set a service level: first response within one working day, and a clear owner for each queue. If the team is blocked, a short synchronous session can resolve in ten minutes what would take a day of comments.

Culture matters more than tooling here. Comments should address the code, not the person, and should explain the risk rather than assert authority. "This will fail when the list is empty" is useful; "this is wrong" is not. Praise good changes publicly, and keep correction private where possible.

Review your own code first

Before requesting a review, read your own diff in the browser. You will catch debug statements, commented-out code, unrelated formatting and forgotten tests. This small step removes a category of comments that waste everyone's attention and signals that you respect the reviewer's time.

For the wider delivery picture, read our small-team shipping guide. For the security questions worth asking in review, see our cybersecurity checklist.