Foster your team spirit with distributed code reviews

Get back in touch with your distribute teams – and improved your products as a result.

Distributed teams are no longer an exception in modern working environments. Working remotely – whether from home or an overseas office – has become the new normal thanks to evolving technology and new working methods.

However, this leaves teams with a new challenge to master: not being in the same place and time zone makes it harder to connect to each other on a personal level and harness that elusive team spirit. Communication is oftentimes outsourced to written chats or email, leaving the team with little to no room to casually chat on a personal level. Also, sensitive topics, such as critiques, are more difficult to express over chat due to possible misunderstandings.

At yasoon, we experienced all these challenges. As an Atlassian Platinum Partner, our core business is improving workflows, but when one of our founders relocated to the US for several months (the majority of our staff is based in Europe), our own standard workflows were interrupted. We struggled to maintain the social bonds that had become an important part of our company culture.

More specifically, our distributed code review process was no longer working for us. All of our remote team members work on our IT team, and need constant feedback. It was hard to find the right time to talk, written feedback was not as thorough as it should have been, and the team just didn’t feel connected. Recognizing this problem, we modified our code review practices to fit to our distributed team, always keeping the agile manifesto in mind: “individuals and interactions over processes and tools.” Why was this so important to us?

Gallup’s State of the American Workplace study found that the work engagement of remote workers is hindered by a lack of relationships with coworkers. The authors suggested that managers must bring a social environment into the digital world. So we decided to try doing that with our code reviews.

Why we do code reviews

We believe code reviews offer two major opportunities for improvement: to improve code and to improve morale. Of course, when you discuss code, there’s an opportunity to enhance it – you can learn about bugs and break down code silos through knowledge sharing while discussing the topic at hand. And eventually, your code quality will improve.

Code reviews are also an opportunity to interact with colleagues through the lens of collaboration and discussion. This fosters the growth of working relationships, helps define team culture, and can ultimately serve to improve morale.

Why asynchronous code reviews don’t work

When your team is distributed, it can be difficult to organize your code reviews the same way a local team would, which is why remote teams often resort to asynchronous code reviews. There are plenty of excellent tools for time-independent code reviews, but the focus here is on the importance of individuals and interactions.

Distributed teams can’t thrive without a decent process powered by the right tools. But in our experience, when you take the synchronicity out of your communication, the focus becomes only on the essentials: corrections and bugs. Focusing on these priorities will yield decent code, but doesn’t improve overall code quality in the long run. And have you ever seen someone ask, “How are your kids?” in your GitHub repository?

While there are people who prefer a more goal-oriented approach, we believe this is outdated. Doing good work is about much more than just getting the job done.

How we conduct remote code reviews

Gallup’s study found that face time with managers and coworkers boosts engagement, and in our experience, combining the benefits of code review tools and synchronous communication immensely benefits distributed teams. In fact, all meetings with the purpose of giving feedback will benefit from being held simultaneously. You would never do a quarterly review in Slack.

1. Preparation

Using Jira, we recommend creating a multi-user picker custom field called “reviewer” for your project. In your next scrum planning, assign one or two reviewers in this field for each issue planned for that week. That way, you’ll have already agreed on an expert for that specific topic, and those who choose which issue to work on don’t need to search for a suitable reviewer themselves.

When your code is ready for review, use the Outlook Meetings for Jira app to schedule an appointment with your reviewers. Meeting slots are already suggested in your Jira issue, taking time zones into consideration.

The app also sends Outlook meeting requests with a unique Microsoft Teams call-in URL, also shown in the Jira issue. We recommend scheduling the meeting to give the reviewer enough time to prepare – distant time zones can even be a benefit, giving reviewers time to prepare “overnight.” Reviewers now comment the code in Crucible or GitHub, so every note is well documented. At the same time, you can directly connect with your colleagues about the related issue via Microsoft Teams, using Microsoft Teams for Jira.

2. The code review meeting

You are now ready to start your synchronous code review using a web conferencing tool like Microsoft Teams. We highly recommend using video chat to make your code review as “social” as possible.

By screensharing the reviewer’s comments in Crucible or GitHub, you can now discuss code changes. Synchronous meetings offer a chance to discuss issues more deeply and exchange thoughts and ideas more freely, which helps improve code quality in the long term. There’s no need to go into detail about style and format. If you want to take your discussion to the next level, you can even use Visual Studio Code Live Share to try out ideas in the code together.

As always, it’s important to consider how criticism is voiced. Try to use words that show your appreciation. In general, asking honest questions is more likely to hit the right tone than making unrealistic demands or giving orders – and a face-to-face conversation, with all the subtle nuances of tone of voice and facial expressions, is more likely to preserve feelings than written feedback in the form of many, many comments.

And don’t forget to take the opportunity to get to know your colleagues a little better. Being “unproductive” for five minutes never killed any company.

3. Incorporate changes

When the meeting is done, it is of course the developers’ job to incorporate any changes that were discussed. The review tool helps reviewers look back at the comments and tick off what’s done, and the reworked code will be reviewed once more – usually asynchronously, but of course feel free to set up another call if there is still something that needs discussing.

Outlook Meetings for Jira lets you know whether the reviewer is available with a green indicator beside his or her picture.

By definition, distributed teams don’t sit in the same location; you can’t enjoy an impromptu chat at the coffee maker. Using synchronous code reviews to connect with your colleagues can help build team morale, and will certainly benefit short- and long-term code quality.

At yasoon, we used this workflow to get back in touch with each other. In doing live code reviews on a regular basis, we’ve found creative ways to solve our bugs together as a team. This not only made our code significantly better, but also gave us a chance to talk about subjects besides this specific code, even if it was about a customer using our apps in an interesting way, or what the weather was like in San Diego. We’re prioritizing socialization in our workflow, and our code and our job satisfaction are the better for it.