What a review is for
A code review is a second person reading a change before it joins the shared code. It catches mistakes, but that is only one of its purposes. It also spreads knowledge about how the system works, keeps the style consistent, and gives the author a chance to learn from a different point of view.
A review is not a test. A reviewer reading code will miss things that running it would show, so a review complements automated tests and does not replace them. It is also not a contest or an inspection of the author’s ability. The most useful framing is that both people share the same goal: the change should be correct and understandable.
Before you read the code
Spend a minute on context. Read the description of the change, and any linked issue or requirement. A reviewer who does not know what the change is meant to accomplish can only comment on style.
Check the size. Very large changes are hard to review well, and attention tends to drop sharply as the amount of code grows. If a change is too big to hold in your head, it is reasonable to ask the author to split it. Small, focused pull requests are one of the biggest favours an author can do for a reviewer.
What to look for
A rough order of priority keeps the review useful.
1. Does it do what it is supposed to? Compare the change with the intent. Does it handle the stated case? What about empty input, missing values, or failure of something it depends on? Walking through one or two realistic scenarios in your head often reveals gaps.
2. Is the design sensible? Does the change fit the existing structure, or does it introduce a second way of doing something the code base already does? Is the responsibility in the right place? Design concerns are better raised early, because they are expensive to change late.
3. Are there tests? Look at whether the new behaviour is covered, and whether the tests would actually fail if the code were wrong. A test that cannot fail is not protecting anything. Reading the unit tests first is often a quick way to understand what the author intended.
4. Is it readable? Could you understand it without the author present? Check names, the length of functions, and whether tricky logic has an explanation. Good code comments explain why something is done, not what the next line already says.
5. Risk areas. Be more careful around security, data handling, concurrency, error paths and anything that is hard to undo. Where the code touches safety, health, money or legal obligations, follow the review procedures that your industry and organisation require; a casual read is not enough.
6. Style and small matters. Formatting and naming conventions are best handled by automatic tools, such as those run in a continuous integration pipeline, so that reviewers can spend attention on things a machine cannot judge.
Writing comments that help
The same observation can be received very differently depending on how it is worded.
- Describe the code, not the person. “This loop never checks for an empty list” is about the code. “You forgot to check for an empty list” is about the author.
- Ask questions when unsure. “What happens here if the file is missing?” invites an explanation and sometimes reveals that you missed something.
- Give reasons. A comment that explains why a change is suggested can be evaluated; a bare instruction can only be obeyed or resisted.
- Offer an alternative where you have one. A short suggestion saves a round trip.
- Separate must-fix from preference. Many teams use a simple convention, such as marking optional remarks as “nit” or “suggestion”. Authors then know what blocks the merge and what is merely an idea.
- Say what is good. Pointing out a clean solution is accurate feedback, and it helps people know what to repeat.
Some contrasting examples:
| Less helpful | More helpful |
|---|---|
| “This is wrong.” | “I think this returns the wrong value when the list is empty. Could we add a case for that?” |
| “Why would you do it this way?” | “I was expecting to see the existing helper used here. Is there a reason it does not fit?” |
| “Rename this.” | “Suggestion: total_price might be clearer than tp, since it is used in several places.” |
Broader advice on giving constructive feedback to colleagues applies here as well, since a review is a form of feedback delivered in writing, where tone is easy to misread.
Keeping reviews timely
A change waiting for review blocks the author. Reviewing promptly, even if briefly, keeps work moving. If you cannot get to it soon, say so, or suggest someone else.
Equally, do not let speed turn into approval without reading. If you did not look closely at part of a change, say that rather than approving silently.
Handling disagreement
You will sometimes disagree with the author. State your concern and your reasoning once, then listen. Often there is context you lacked. If the disagreement is about preference rather than correctness, it is usually best to defer to the author or to an agreed team convention. When the point is genuinely important and unresolved, a short conversation, in person or by call, is often faster than a long comment thread. For more on that, see how teams approach technical disagreements.
A simple checklist
- I understand what the change is for.
- The size is manageable, or I asked for it to be split.
- It handles the main case and the awkward ones.
- Tests exist and would catch a failure.
- I could understand the code without asking.
- My comments are specific, explained and clearly marked as required or optional.
- I said what was done well.
Remember the limits
A review reflects what one person noticed in a limited time. It will miss problems. Treat it as one layer of defence alongside testing, careful design and sensible release practice, not as a guarantee that the code is correct.