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 Marketplace Top Vendor, 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 2017 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.
We designed a workflow specifically for distributed teams, with two priorities: it must be practical, and it must improve social interaction. (We use Atlassian and Microsoft software for illustration purposes, but you can adjust the steps according to your chosen tools.)
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. A similar option is available if you’re using Zoom and Jira Service Desk.
Schedule a meeting right in Jira with Outlook Meetings for Jira
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.
2. The code review meeting
You are now ready to start your synchronous code review using a web conferencing tool. 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.
In your Jira issue, the green dot shows you that the user is available right now. Just call the user directly via Microsoft Teams.
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.
Although asynchronous tools are helpful for distributed teams, we strongly recommend live meetings as an opportunity to connect and discuss on a much deeper level.
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.
Are you using Outlook and Jira and want to schedule meetings more easily?
Try our Outlook Meetings for Jira app for free on the Atlassian Marketplace!