Posted by j.laird on 18 March 2022 - 10:00am Image by Naassom Azevedo from Pixabay

By SSI Fellows Dominik Krzeminski, Thibault Lestang and Valerio Maggio.

There are many reasons to do regular code reviews. One of them is improving the readability of your code. Source code is often the only documentation available for research software, and readability is, therefore, key to anyone trying to reproduce or build upon your research. Would you ever publish a paper without any feedback on its draft?

Code Review is a software development practice that aims to improve the quality of source code through constructive discussions, typically involving the author and one or more reviewers. The process is, however, different from academic peer review. In fact, code review occurs frequently throughout the research process in a rather informal fashion, for instance with lab members as reviewers.

In addition to the code itself, code reviews benefit the research community by facilitating the transfer of skills and knowledge. Beginner programmers learn from more experienced colleagues, who themselves do not necessarily remember how it was getting started. Practised within a research group, code review lowers the entry barrier for newcomers to a project and reduces imposter syndrome [^1]. Moreover, a systematic code review culture helps group members to stay up to date with their colleagues’ work, enabling higher levels of collaboration, cohesion and trust. Principal Investigators will be interested in this: over are the days when knowledge leaves the group together with the students that carry it [^2].

Despite being common practice in the software industry and open-source communities, researchers rarely review each other’s code. A common misconception is to consider code review as a high-stake assessment of work. By approaching code review in a similar way to a paper peer-review process, some researchers are willing to carry it out only at the end of the development process. Instead, code review is effective throughout the research process, from the first few lines of code all the way to the publication stage [^3].  Generally, however, the code review process is unknown to many - and those aware of it struggle with a lack of incentives, guidance as well as exposure to good practices.

Code Review Workshop

The idea of a code review workshop was born during the 2021 edition of the SSI Fellows Selection day. An event planning session involving Micheal Berks, Dominik Krzeminski , Thibault Lestang, Valerio Maggio and Peter Schmidt laid the groundwork for an event that could raise awareness about the code review process. It would also disseminate good practices, making it possible for attendees to propagate them within their own research communities. 

Fast forward to February 2022, when the interest in the code review workshop exceeded all expectations. We could only accept 40 participants, yet there were almost 80 people signed up to the waiting list. That shows that scientists are eager to improve software quality. Among all the participants, only a handful reported having tried code review before, mostly as a one-off event and without guidance. However, we know that tools are out there, we just need to increase their adoption.

The event was hosted by us with excellent support from Dr Tiziano Zito from Humboldt University in Berlin, and Dr Zbyszek Jędrzejewski-Szmek, currently a software engineer at RedHat. We kicked off with a talk by Thibault, who gave a birds-eye view of the code review practices in research. Next, our guest speakers from continental Europe demonstrated a live demo of a typical code review cycle. After a short break, we split out into (virtual) rooms, where we put our hands on actual code and performed some reviews. We used Python and R, as the vast majority of our participants declared familiarity with those technologies, however, we highlighted that the skills are transferable across the programming languages and disciplines. Finally, we concluded the event with a summary by Dominik and Valerio, who also moderated the vivid Q&A panel.

Help from the community

Most of the discussion touched upon practical advice on how to get started with code reviews. Particularly, how to find people to do it with. Here is a summary of the main takeaway points.

People who seek a review and have no clues on where to start might want to initiate a discussion with lab members. It doesn't really matter whether they are familiar with a code, or project. They can still provide valuable feedback or suggestions [^4].

Another place to look for advice is a supervisor or a dedicated local organisation. For example, the Oxford Code Review Network (OxCRN) is a community of researchers and practitioners focused on helping with code reviews. It is centred around a GitHub repository where participants are encouraged to play both roles: reviewers, or reviewees and there is no particular level of experience required to join. The mission of OxCRN is to foster a community of research software at the University of Oxford, enabling the transfer of knowledge and software skills across researchers of various levels of experience and research communities.

Ultimately, if no such initiative exists at your University, why not start your own "Code-Clinic'' group? You would be surprised how many researchers, just outside your inner circle, share similar struggles and experiences with programming, and organising your own community of practice on code review is a wonderful way to get started, and to share your mutual experience.

We encourage everyone to find their own way to start with code reviews in their local scientific communities. If you still would like to learn more, get in touch with us, or keep an eye on SSI social media, where we will announce the next editions of the Code Review Workshop.

[^1]: Fear of not being skilled or experienced enough.

[^2] But this is not meant as a solution to short-term research contracts ;)

[^3]: Code Reviewing in the Trenches (MacLeod et al 2017)   http://chisel.cs.uvic.ca/pubs/macleod-IEEESoftware2017.pdf

[^4]: Code Review as a Simple Trick to Enhance Reproducibility, Accelerate Learning, and Improve the Quality of Your Team’s Research (Vable et al, 2021)  https://academic.oup.com/aje/article/190/10/2172/6218064