Code review is one of the most valuable moments in a development team's work, and also one of the most misunderstood. Done badly, it becomes a bureaucratic ritual where people approve without reading, or a contest to see who can find the most flaws in someone else's work. Done well, it spreads knowledge of the code, catches errors before they reach users and gradually raises everyone's level.
What it is really for
Many people think code review is mainly about finding bugs. That is partly true, but the most important benefits lie elsewhere:
- knowledge sharing: at least two people know every part of the system;
- consistency: the code follows shared conventions and stays understandable;
- design: a second look spots simpler solutions or structural problems;
- mutual learning: the reviewer learns from others' code as much as the author does.
Keeping these goals in mind changes the tone of a review: you are not looking for someone to blame, you are improving a product together.
Small is better
The factor that most affects the quality of a review is the size of the change. Faced with fifty lines, a reviewer reads every detail carefully; faced with two thousand, they skim, tire and approve. The author therefore has a precise responsibility: preparing small, coherent changes.
Some practices help:
- separating refactoring from behaviour changes, in two distinct requests;
- splitting a large feature into steps that can be integrated one at a time;
- writing a clear description: what changes, why, how it was verified;
- rereading your own diff before asking for review, removing debug code and accidental changes.
What to check, in order of importance
Not all comments have the same value. A useful order:
| Priority | Question | Example |
|---|---|---|
| 1 | Does it do what it should? | Does the calculation handle an empty cart? |
| 2 | Is it secure? | Is user input validated before use? |
| 3 | Is it sensibly designed? | Does this logic really belong in this module? |
| 4 | Is it tested? | Do the tests cover edge cases and errors? |
| 5 | Is it readable? | Do the names explain the intent? |
| 6 | Does it follow the style? | Indentation, formatting conventions |
The last item deserves a separate note: style should be delegated to machines. Automatic formatters and linters run in the pipeline eliminate whole categories of repetitive comments and leave human reviewers the questions that require judgement.
How to write constructive comments
The way a comment is written matters as much as its content. Some practical rules:
- Comment on the code, not the person. "This function does three different things" instead of "You wrote a confusing function".
- Explain why. "Better to use a transaction here: if the second insert fails, the first is left orphaned" is useful; "Use a transaction" less so.
- Distinguish blocking from optional. Many teams use prefixes such as "nit:" for minor details, so the author knows what must change and what they can weigh up.
- Ask questions when you are unsure. "What happens if the list is empty?" invites reasoning and sometimes reveals that the case is already handled.
- Acknowledge things done well. An elegant solution deserves to be noticed: it reinforces good practice.
The author's role
Receiving a review requires just as much maturity. A comment on your code is not a judgement of your worth. If a reviewer misunderstood something, the next reader will probably misunderstand it too: it is a sign that a better name or a comment is needed. When you disagree, argue with facts and examples; if the discussion drags on, a short call often resolves more than ten messages.
Timing and team habits
A review that arrives three days later blocks work and encourages ever larger requests. Many teams set a simple goal: first response within the same working day. Other useful habits:
- rotating reviewers, so knowledge does not concentrate in one person;
- using a short checklist for aspects that are often forgotten, such as database migrations or configuration variables;
- not approving what you have not understood: asking for explanations is part of the job.
What review cannot do
Human review does not replace automated tests, static analysis or security checks. An attentive reviewer may notice an obvious vulnerability, but cannot mentally verify every execution path. Code review works best as the last layer of a system that has already filtered out mechanical errors.
In short
- Code review is mainly about sharing knowledge and improving the design, not just finding bugs.
- Small, well-described changes produce better reviews.
- Check correctness, security and design first; leave style to automated tools.
- Comment on the code, not the person, explain why and flag what is blocking.
- Respond quickly: slow reviews lead to ever larger requests.
