This article is part of a multi-part series on remote digital product development. As a fully-distributed organization since 2016, DockYard’s experienced teams of project managers, designers, and engineers have learned a lot about how to seamlessly collaborate across disciplines and time zones.
As teams migrate from offices to remote work, our processes need to adapt. The ability to physically check in with our co-workers no longer exists. Working fully remote is quite a big shift. It turns social dynamics upside-down in ways that might not feel normal. What is a development team to do?
Being developers, we have particular advantages that other knowledge workers do not. Our work becomes digital and can be shared across the world in seconds. Our natural desire is to get that work delivered as soon as possible, but how do we increase our confidence when we do? How do we know that our work is high-quality and ready to go?
Right now, more people than ever are reviewing code remotely, likely in pull requests (PRs). So, in this dispatch, we will focus on simple tips and advice to make the process painless, positive, and productive.
Be small
We are always encouraging developers to make the amount of code in PRs small enough so that it can get a quick review. It’s smart to keep PRs focused on one thing — whether that is a feature or a bug fix. Why hold up one feature from production when another still needs work? The smaller the proposed change, the less context that is required to get up to speed and give a worthwhile review — and the faster you can get on to the next thing. Not only does this ultimately make for less code to review, but it also likely decreases the complexity of the code that’s being reviewed. This also makes it less likely that mistakes will be made or that any negative feedback will come up at all.
Be clear
Reviewing smaller PRs is easier, no doubt. However, sometimes they can pile up, or in some circumstances it’s not practical to break down a larger PR. We vastly prefer asynchronous reviews (for hopefully obvious reasons), but there is definitely a place for getting together face-to-face and getting a quick rundown to be really clear about what’s going on.
If you’re running into this situation, and the PR is a reasonable size, we encourage you to ask the PR author to walk you through it in a 15-minute chat. After you get off the call, if you can’t look it over and approve with confidence in 30 minutes, that work likely needs to be broken down into separate PRs, or a different solution needs to be considered.
If the PR size is larger, or complex, it can also be helpful to have a dedicated session with the explicit goal of getting the work approved before the session is over. This increases focus and urgency, which can really help move things along. We don’t recommend this approach all the time, but it can be a powerful tool every once in a while.
Be kind
Our jobs are not only to write professional software, but also to foster and maintain healthy team dynamics. This does not just apply to leadership and management; it applies to every team member. It’s even more important when you’re remote.
To that end, be kind in pull requests. Be positive and constructive in your tone. Be clear and concise. Don’t be afraid to use lots of positive emoji. With the lack of in-person conversation cues, sometimes even well-meaning feedback can get lost in translation. Remember the negativity bias: your neutral feedback can come off as negative even if you didn’t mean it to. This is why it’s important to give explicit feedback and ask important questions.
Lastly, you’re reviewing code, not passing judgment on people. Be careful to call out the code and not the person. Remember, you’re asking for clarification, not trying to put them on the spot. It can often help to point out times when you’ve made the same mistake in the past.
Be questioning
A good strategy during a review is to ask questions instead of making statements. I cannot count the number of times I have stated in a PR comment what I thought was a fact, but was actually a misunderstanding of the current state and was totally wrong! If I had asked instead of told, then that would have very likely engaged the other person more and avoided an embarrassing moment for me.
Even if you’re asking questions, you want to be careful not to put the author on the spot. One great way to get clarity on why things are the way they are in the code is to use “help me understand” questions. Resist the urge to criticize code and instead ask, for example, “can you help me understand why you took this approach?” It both empowers and puts the onus on the author to explain their reasoning, and the tone of the conversation stays inquisitive instead of critical.
Be equal
When reviewing code, everyone is on the same team. In the world of PRs, establishing and maintaining a horizontal peer relationship is critical for getting candid feedback and leveling up junior engineers more quickly. Everyone’s code gets reviewed, so everyone is open to the same critique.
If a junior engineer’s code is getting reviewed laterally, it helps build rapport quickly. If done right, instead of feeling like a superior is picking apart their work, code reviews become a time for teasing out thinking and motivations, and getting the author to verbalize their thoughts more clearly. It might even get them to realize mistakes they’ve made and self-correct them.
When a junior engineer is reviewing code from a senior, the answers to the questions become teaching moments. It is a chance to show off the collaboration skills the junior engineer has been developing. It also teaches that it’s okay to point out issues in code, even if someone more senior than you wrote it. Reviewing code is a huge opportunity to increase shared knowledge, team cohesion, and emotional security, so it is critical that more junior engineers practice review skills early and often.
We are excited for more and more developers to increase their skills in remote collaboration. As an all-remote agency, DockYard has been practicing and perfecting these skills for years. Beyond improving code quality, code reviews have a surprising effect on both team dynamics and professional development.
DockYard is a digital product agency offering custom software, mobile, and web application development consulting. We provide exceptional professional services in strategy, user experience, design, and full stack engineering using Ember.js, React.js, Ruby, and Elixir. With a nationwide staff, we’ve got consultants in key markets across the United States, including San Francisco, Los Angeles, Denver, Chicago, Austin, New York, and Boston.
