“A code review is a synchronization point among different team members and thus has the potential to block progress,” wrote Palantir engineer Robert Fink on their engineering blog. Code review can become a bottleneck if it doesn’t happen promptly—at Palantir, “on the order of hours, not days”—that prevents code from shipping.
That’s what makes code review such a challenge for remote teams, especially those split across multiple timezones. Remote teams tend to rely on asynchronous communication and workflows, because team members aren’t necessarily online at the same time. They often need to design for the inability of reviewers to promptly unblock fellow engineers by providing a code review.
We talked with several remote teams, and they shared with us three lessons that they learned in designing code review processes that work for teams with minimal or no timezone overlap at all.
1. Write longer but fewer comments in code review
Keeping comments short seems like it would speed the code review process up. But on a remote team, if every comment requires a response (or two or three) for clarification and context, then one quick comment can become a long, laborious thread spread out over multiple days.
At online course creation software startup Podia, CTO Jamie Lawrence solves this problem by asking his team to write—extensively—when making PRs and reviewing code.
The biggest challenge to remote work is writing. Not only getting people to write, but getting them to write more, way more, and put more into the pull request. It’s not two sentences—it’s three paragraphs.
Lawrence lives in Ireland, which is five hours ahead of the United States where the majority of his team is based. Lawrence says he “tends to be a night person” and does his heads-down coding in the evening, while the other developers mostly do theirs in the morning, US-time, so they have minimal timezone overlap.
That minimal overlap—coupled with the desire to protect developer productivity from interruptive meetings—means that they can’t “rely on real-time chat, having walkthroughs together, or pairing.” Instead, “it’s really important [for them] to be able to write things out.”
A good PR for Podia starts with a meaty writeup to accompany any pull request. Lawrence writes in the company wiki that the code review template “is a good starting point” for providing relevant context and background on the PR, but “you should always consider writing more [than the template requires].”
The writeup should cover “what the purpose was, and the choices that have been made along the way.” Code owners should “tell the story of the PR and [not] assume the reviewer knows anything about the feature, or the context, or the struggles [they’ve] had implementing it.”
As a reviewer, Lawrence prompts code owners for more writing and detail by asking open-ended questions. In Podia’s workflow, “every comment you leave is going to be an open-ended question.” By asking code owners about the necessity of a given change or the effects it might have on the rest of the system, reviewers can encourage deeper thought and a more thorough response.
2. Lean into the pull request as a communication channel
Sharing physical proximity in an office means that there are more opportunities to bring up vocally that you need a code review and to move the process forward. You can ping people on Slack and reliably expect that they’re online and at work. But on remote teams, especially those divided over multiple timezones, those opportunities are fewer or nonexistent.
Formspree—a contact form to email service—found that by minimizing use of Slack, engineers live in and depend on GitHub even more, which noticeably increases their responsiveness to comments in PRs. As cofounder Cole Krumbholz told us:
Engineers don’t always check Slack, but they’re pretty much always in GitHub checking PRs and comments. If you ever respond to these guys in a PR, you’ll always get them. Now the conversation’s easier when it happens there.
Prior to Formspree, Krumbholz worked at Squarespace, where it was typical to ping engineers on Slack for code review and quickly chat there about any issues that came up before merging and deploying.
At Formspree, Krumbholz and his cofounders have designed the company around their lifestyles. They’ve become a remote team so obsessive about asynchronous communication that they hardly even use Slack anymore.
We have one weekly meeting, and that’s the only point at which we’re all communicating in real-time. Everything else is asynchronous. Slack is not a reliable channel for us because we are on different timezones and in different personal schedules. Fundamentally, people [at Formspree] don’t want to be online all the time.
GitHub has become the communication hub that’s replaced Slack, centered on changes in the code as “the most mandatory, the most essential communication” for a software company. They tend to “get PRs out early and have work-in-progress PRs that people can look at,” which describe the problem and feature scope, not just the code. That opens up “fruitful conversations in the PRs that have a combination of both code and product feedback.”
Doubling down on the asynchronous PR workflow has made it more reliable and ongoing, obviating the need for interruptive communication to move along the code review process.
3. Schedule overlap time and sync up
Looping in additional stakeholders for comment during code review often helps with more complex PRs that touch different parts of the codebase. But if new stakeholders live in different timezones, the PR can spend a lot of time idle, sitting and waiting for engineers to come online and find the time to leave feedback.
Instead of trying to make this work asynchronously, the team at Taskade—a unified workspace tool for remote teams—has decided that the easiest thing to do is batch all of the PRs, get online at the same time two or three times per week, and resolve them all in a synchronous meeting.
We batch everything. We don’t just do the code review and merge every single day. That’s way too cumbersome. We do it maybe two or three times a week, but when we do do it, we go through all of it at once and merge everything that’s possible.
The Taskade team is split between Singapore, Malaysia, California, and New York. They’ve experienced what they call PR “ping-pong,” where comments bounce around between several stakeholders, all in different timezones. As John Xie, Taskade cofounder and CEO, told us:
There are pull requests where it goes back and forth between Dionis [CPO in New York], myself [CEO in San Francisco] and Sheila, one of our engineers in the Philippines, and then it gets finally reviewed by Stan [CTO in Singapore] and then merged.
That can be “a lot of back-and-forth,” and the cycles can be long because the timezone spread is so large—13 hours—between Singapore and New York.
In designing a solution to this problem, they decided to follow the advice of their first investor, Aaron Iba, the cofounder of Etherpad and former partner at Y Combinator: “Keep it simple.”
A synchronous meeting, held a few times a week, makes it easy to synthesize feedback from all stakeholders quickly, and then run all of that through Stan, the CTO, who sees every change that goes out, merges to master, and deploys. That’s how they strike the right balance between frequent product releases and improvements and ensuring that changes “don’t cause a lot of technical debt and still represent quality work which [we] can build on top of in the future.”
Conclusion
While Formspree’s and Podia’s answers to the challenges of code review on remote teams are to lean even more into asynchronous communication, Taskade finds that it’s logistically simpler just to schedule a synchronous meeting a few times a week.
How you make code review work for your remote team will be highly context-specific, but we generally find that teams seek to facilitate reviewer responsiveness with high quality feedback while minimizing interruption and bureaucratic overhead.
Remote teams don’t have physical proximity and shared timezones to fall back on. But if they use the challenges of remote work as an opportunity to design deliberate, explicit processes, then they can reap the benefits of working remotely without incurring the bottlenecks.
What challenges have you encountered doing code review in your remote team, and how have you overcome them? Email me at lyal@pullrequest.com and tell me your story.
