Code review is one of the highest-leverage activities in software engineering. Done well, it catches bugs, spreads knowledge, and raises the bar for the whole team. Done poorly, it becomes a bottleneck that breeds resentment.
Here is what we have learned about making reviews work.
Review the Right Things
Not every comment needs to be about correctness. The most valuable review feedback falls into a few categories:
- Bugs and logic errors — the obvious one.
- Design concerns — will this approach scale? Is there a simpler way?
- Readability — can someone unfamiliar with this code understand it in six months?
- Missing edge cases — what happens when the input is empty, nil, or enormous?
Avoid bikeshedding on style issues that a linter should handle. If you find yourself arguing about bracket placement, add a linter rule and move on.
Keep Reviews Small
Large pull requests get rubber-stamped. Small, focused PRs get thoughtful reviews. Aim for under 400 lines of meaningful changes per PR.
If a change is inherently large — say, a database migration with model updates and API changes — break it into a stack of dependent PRs.
Provide Context
As an author, make the reviewer’s job easier:
- Write a clear PR description explaining why, not just what.
- Link to the relevant issue or design document.
- Call out areas where you are uncertain and want extra scrutiny.
Be Kind, Be Direct
Use “we” language: “We should add a nil check here” instead of “You forgot a nil check.” Suggest, don’t demand. And when code is good, say so — positive feedback is underrated.
Automate What You Can
Linters, formatters, type checkers, and CI pipelines should catch the mechanical stuff before a human ever sees the PR. This frees reviewers to focus on design and logic.
For more on setting up local development environments that support this workflow, see Docker Compose for Local Development.