Remote teams
Code review agreements for a remote team
Remote code review works with small pull requests, a response within one working day and a pipeline that checks everything a machine can check.
Remote code review works when pull requests are small, reviewers respond within a working day and the pipeline checks everything a machine can check. That leaves the reviewer time for the design and for the question of whether the code does what the ticket asks. Write these agreements down and keep them in the repository, so a new developer knows them from day one.
Why distance changes code review
In an office you walk over to someone's desk. In a remote team the pull request is often the only conversation about the code, and a question in a review comment that gets an answer the next morning costs a day. That is why pull request size and response time weigh more heavily than they do in an office.
The review is also where a new developer learns how your team writes code. Whatever is written there stays on record, so write comments that someone can still follow six months from now.
Small pull requests
A small pull request gets reviewed sooner, and better. Google's code review guidelines say 100 lines is usually a reasonable size and 1,000 lines is usually too large. The number of files matters too: a 200-line change in one file can be fine, while the same change spread over 50 files usually is not.
Always put refactors and behaviour changes in separate pull requests. With the refactor, the reviewer can quickly confirm that nothing changes. With the behaviour change, they see exactly what does. Unfinished work can be merged behind a feature flag, so nobody spends a week on one big branch.
Responding within a working day
Google's guidelines set one business day as the maximum time to respond to a review request. For a remote team I would be stricter. Our developers work from Serbia, in the same time zone as most of Western and Central Europe, so a response within a few hours is realistic.
What helps:
- A fixed moment for reviews, for example at the start of the day and after lunch, before picking up new work.
- Fixed reviewers per part of the codebase. On GitHub you do this with a CODEOWNERS file, and code owners then get review requests automatically (except on draft pull requests).
- A rule on the main branch that requires approval from a code owner.
- An agreement for pull requests that sit idle: after half a day, you mention it in the team channel.
If you want early feedback on an approach, open a draft pull request and ask for it directly. That saves a round if the approach turns out to be wrong.
What the pipeline checks
A reviewer should not be commenting on anything a tool could have caught. Run the pipeline before the review and make these checks required:
- formatting and linting
- type checking and the build
- unit and integration tests
- a scan for vulnerable dependencies
- a scan for secrets in the code
If the same comment keeps coming back in reviews, turn it into a linter rule so nobody has to type it again.
Our developers use AI coding tools such as Claude Code every day. Generated code goes through the same pipeline and the same review as any other code, and the author has to be able to explain every line. An AI review tool can do a first pass, but a human gives the approval. The agreements to make about that are in AI coding tools in a remote team.
What the reviewer looks at
The reviewer is left with the work a tool cannot do:
- Does the code do what the ticket asks, and does it meet the acceptance criteria?
- Does the solution fit the architecture, or does it add a second way of doing the same thing?
- Do the tests check behaviour, or only the implementation?
- Does every new endpoint check whether the user may access this data?
- What happens if an external call fails or a migration stops halfway?
- Will a colleague be able to read this in six months?
For the security questions, the OWASP Top 10 is a good basis for your checklist.
Tone in written feedback
In writing, everything sounds harsher than you meant it. In a distributed team you also often write in English, even when it is nobody's first language. A few agreements help:
- Ask a question instead of giving a verdict. "What happens here if the list is empty?" lands better than "This is wrong."
- Show how much weight a comment carries, for example "nit:" for details and "blocking:" for what really has to change.
- Explain why, and suggest concrete code where you can.
- If a discussion goes back and forth more than twice, take a ten-minute call and write the outcome in the pull request.
Put these agreements in a CONTRIBUTING file and add a pull request template covering what changes, why, and how to test it. How our developers join your team and your review process is described under how we work.
Sources
Frequently asked questions
How big should a pull request be?
Small enough for a reviewer to read in one sitting. Google's code review guidelines call 100 lines usually a reasonable size and 1,000 lines usually too large. Split big changes into steps that can each land on their own.
How quickly should you respond to a code review request?
Within one working day, and preferably the same day. Google's guidelines set one business day as the maximum time to respond to a review request. If your team shares a time zone, a few hours is a realistic agreement.
What can you automate in code review?
Everything a machine can check: formatting, linting, types, tests, and scans for vulnerable dependencies and leaked secrets. The reviewer can then focus on the design and on whether the code does what the ticket asks.
About the author
Erik Schoorl
CTO and lead architect
Erik founded ESBL together with Bas. He is CTO of Brainpower Group and has final responsibility for architecture and delivery.
More from Erik
