Code Review Guide

ByPeter Volfon2026-03-05

I've been doing code reviews and mentoring for years across multiple projects and seniority levels, collecting notes in the process. This post attempts to be a general, realistic guide for developers, reviewers, and even managers for approaching code reviews in a productive way.

The fundamental goal of a code review is to maintain - preferably improve - code quality and project health.

When done well, it can also be a great everyday tool for personal development and team alignment, creating a positive culture and a feedback loop that increases productivity.

Responsibilities

Solving a task is a joint effort between the developer and the reviewer. Communication is important, the "review" can start as soon as the task is assigned.

Throughout the development process, the developer should aim to find a good balance between working through the task independently and asking for domain information, clarification, direction from the future reviewer. On one hand, high-level issues can be hard and time-consuming to fix after the code is written. On the other hand, this is a great opportunity for learning.

The reviewer must try to balance several factors during code review. The developer should also understand these and be a partner in the process:

Minimum quality standards must be always met.
The review should be personalized, challenging, and constructive to facilitate learning.
The aim is to improve minimum quality standards over time.
The review shouldn't unnecessarily block the developer, who is often under pressure to deliver.

The reviewer is responsible for asking about design decisions and commenting on potential issues. It is also the reviewer's responsibility to decide when these comments can be resolved. Otherwise it becomes hard to track progress.

The developer is responsible for addressing the reviewer's comments. Pointing to a small, easily understandable commit in a "fixed in commit-hash" response can be enough, but simply pointing to large, hard to process commits is not.

Code review stages

The sections below outline what to look for during the different stages of a code review.

Reviewers must manage the time they allocate for a review. If there are issues or questions at any review stage, the related comments should be sent and the review should be paused until these comments are addressed by the developer. Fixing higher-level issues often implicitly fixes lower-level ones as well, so reviewing low-level details when there are higher level problems is usually a waste of time.

1. Overview

Design and architecture:

Is the change directionally correct?
Is the code well-designed?
Is there a simpler, alternative way that achieves the assumed business goal with less complexity?

Dependencies:

Were new external dependencies added? If so, are they necessary and actively maintained?
Does the change introduce new dependencies between parts of the system? It's a code smell, possibly highlighting a design issue.

2. Deep dive

Code structure:

Does the change fit seamlessly into the existing codebase?
Did the developer use the correct existing abstractions and tools?
Is new code placed correctly in the existing code structure? Is it easy to discover?

Functionality:

Are special cases handled correctly? A correct happy path is not enough.
Is the code functionally correct? Does it achieve the correct business goal?
Are the new abstractions clear, generic, and easy to understand and use?
Aren't variables or abstractions unnecessarily specific or over-engineered?

Style:

Does the code follow the existing code style?
Does the change introduce new design patterns? If so, are they necessary?

Security:

Is authentication or authorization necessary? If so, is it done correctly?
Are there any assumptions about the validity of user inputs?

3. Code health

Documentation:

Are non-trivial code segments documented?
Documentation is the source of truth. Has it been updated to match the code changes?

Tests:

Are testing and QA policies followed?
Have tests been added for easily testable changes?
Are there critical, testable changes that lack adequate tests given the project's current testing standards?

Opportunities for improvement:

Is there related tech debt that would be easy to address together with this change?

Notes

Localized technical debt that doesn't leak out of a small unit of code - be that a function, class, or module - can be acceptable under time pressure, but it should be a conscious decision and preferably marked at least with a TODO. Fixing these immediately is a good way to learn and build muscle memory though.

"Let's fix it later" responses to review comments:

They can become a policy, leading to slower development and increased maintenance costs.
The problem often never gets fixed or is fixed later with much more effort.
They degrade code health. For non-trivial issues, future fixes are usually suboptimal.
They actively prevent learning.
They are acceptable if the issue is out of scope for the current change, but they should be addressed as soon as possible.

The boy scout rule (leave the code cleaner than you found it) should be applied as much as time allows.

Learning advice

Your main focus should be on learning to identify design smells. It is more important and harder to master than hard skills.

Don't be afraid to ask or comment, it is a natural way to learn. Nobody knows everything, and nobody produces perfect work all the time.

Try to allocate time to quickly go through other people's changes and comments, even when you are not asked to do a review. It's a simple way to pick up new skills and thinking patterns.