The team at Digital Theatre have been working on the rebuild of our educational platform since the beginning of April 2020. Identifying processes that help a new team collaborate effectively always has its challenges, and it's even more difficult to establish new ways of working when you're communicating with your new colleagues via a screen, rather than sat around the same table. There have been times over the last few months when we've got our processes wrong, though we've always been quick to reflect, remedy and improve. There are also methods we've introduced that have greatly improved our workflow. This article focuses on the benefits of one of these methods; the in person code review.
Here's a quick explanation of what I mean by in person. Most readers will be aware that it's standard practice, both in the workplace and in open source projects, for a developer to complete a piece of work, submit a pull request to a repository and have their code reviewed by other developers. This review normally comes in the form of written comments left alongside lines or blocks of code. An in person code review, however, is one where a piece of work is reviewed face to face - in our case, over video calls - and suggestions are delivered verbally and immediately to the author.
Below I discuss five ways in which the in person code review has helped our team to develop fast, flexible and clean code.
It's true that it doesn't always feel like our in person code reviews are helping us develop faster. At Digital Theatre, we will regularly spend half an hour reviewing code, with this sometimes stretching to 60-90mins. As we do most of our work in pairs, this means that if there's two pairs involved in the review (a pair of authors and a pair of reviewers) we're likely to be spending anywhere between 2 and 6 hours of developer time going over a pull request. This seems like a lot of time to be spending on one piece of work, and it really is - we realise it, and we agree!
So, why do it? You may think that spending 90 minutes reviewing someone else's code is too demanding, and is just eating into time you could be spending on your own work. But code reviews that only happen over comments left on Gitlab or Github end up taking longer to be approved, as there's often a lot of back and forth about changes and suggestions. Consequently, it takes more time for code to get into production, increasing the chance of merge conflicts and complicated rebases and therefore slowing down the whole flow of the team.
Getting everyone onto one call also means that more members of the team understand the code that has been implemented. It broadens everyone's understanding of the codebase, and makes moving on to new tickets and parts of the product less of a jump. In person code reviews can make code you've not worked on directly feel that little bit more familiar.
So yes, these reviews might feel slow and demanding at the time, but overall, we're able to develop quicker because we're ensuring all members of the team have as wide an understanding of the code as possible.
Working from home can be really lonely, especially when we're also socialising less and hiding away from the cold, wet English weather. Our team works in a way that encourages lots of human contact, through daily stand ups and pair programming. In person code reviews are an important part of this workflow and another way of creating opportunities for team members to talk to one another. Everyone in the team is expected to get involved in code reviews, even - and especially - if it's a part of the codebase you don't work in frequently. So, while you might work closely with a few people on a daily basis, you can use code review as an opportunity to get some time with team members you see less often.
Leaving comments on Github, Gitlab or whatever you use for your code reviews is a super useful way of recording your questions and comments for someone else's work. The team at Digital Theatre make loads of annotations on code reviews, either by going through a pull request just before jumping on a call to review the work, or leaving comments while on the call to help the pair go back through and make changes after the review.
However, when code reviews consist only of comments left on the git repository, there's way more scope for misunderstanding between team mates. Tone of voice can more easily be misinterpreted in written messages, leading to frictions between colleagues that would have instantly been cleared up over a video call. Therefore, by making in person code reviews such a integral part of our development process, we're ensuring that effective team communication is always a priority.
We've all been there - you're reading through someone else's code and there's an operator you've never seen, a convention you've not come across before or a decision you simply just don't understand. Sometimes, typing out a question and leaving it as a comment on someone else's code just seems too formal - it can become a 'big deal', when really, it's just meant to be a quick, minor question. A written message on a code review can be seen by the whole team, meaning that developers, especially more junior ones, may be less likely to leave a question they think is 'silly' - something they think they should already know.
Having an in person chat about code normally creates a more informal environment, one that provides developers with more opportunities to ask those spontaneous, niggling 'silly' questions. It downplays the need to find the correct wording and coherence required to write a question down. And perhaps those 'silly' questions are also answered with more kindness than a written comment left on a line of code would be.
Reviewing code on a git repository can put a level of responsibility on the reviewer to point things out and ask questions. An in person code review, however, encourages the developers who worked on a ticket to explain their code to the colleagues who are reviewing it. And while being able to write code is an important part of being a developer, the ability to explain the code you've written is just as important, and arguably a rarer skill amongst software engineers.
Additionally, in person code reviews encourage reviewers to ask difficult questions about why certain techniques have been used, or about the decisions and assumptions that have been made during the coding process. The authors of the pull request will learn how to analyse, explain and defend their choices, and also when to yield to the advice and opinions of their colleagues. It's a great way not only to improve your confidence in discussing how you've coded, but also why you've coded one way and not another.
We'd love to hear your thoughts and suggestions for how to create a more productive and engaged team in the comments below.