Posted by d.barclay on 20 July 2023 - 10:30am

By SSI Fellow Deborah Leem.

Introduction

Code reviews are an essential practice to ensure standards in the software development industry and the area of digital humanities (DH) should be no exception. These comprehensive checks offer a pathway to ensure code is not just valid, but also clear to others, maintainable, and permits the author to grow and further develop skills based on constructive feedback.

Recently, I had the pleasure of hosting a workshop focused on the importance of code reviews, sponsored by the Software Sustainability Institute Fellowship programme. This was done as part of my Fellowship and supported by the UCL Centre for Digital Humanities. The event saw a diverse mix of attendees, from digital humanities researchers to research software engineers (RSE) and software developers. Together, we looked to understand how to promote the practice of code reviews in academia.

In this blog post, I'd like to take you on a journey through the insightful discussions, presentations, and collaborations that shaped this event. Whether you're new to code reviews or an experienced RSE, I hope this reflection inspires you to explore and enhance your code review practices.

The Art of Code Reviews

In this first session, our presenters, Michael Robinson and Eugen Mihali, unpacked the essentials of code reviews. They provided a detailed guide on what constitutes a code review and the crucial aspects to pay attention to. They emphasised the necessity of balance - while it's not required to scrutinise every single detail, being open to regular reviews is an important step in broadening one's knowledge and understanding of key concepts.

The session highlighted the human aspect of code reviews. Code often feels like an extension of ourselves, making harsh feedback feel personal. This highlights the importance of delivering feedback constructively and, conversely, maintaining an open mind to assimilate ideas that deviate from the original concept.

The presentation unveiled two effective approaches to code reviews. The first is the face-to-face method, which nurtures stronger relationships and adds a personal touch. This could be as simple as a low-tech session examining code on paper. However, geographical boundaries shouldn't limit our collaborations. Tools like GitLab and GitHub excel at supporting remote teamwork and facilitating feedback on code. While they may lack the immediacy of personal interaction inherent in live meetings, these tools make up for it by offering asynchronous ways of working, allowing for efficient use of time and accommodating different time zones.

We explored how static analysis tools can supplement code reviews. When working in an Integrated Development Environment (IDE), code can be checked in real-time against style guides like PEP8. This practice ensures adherence to standard practices and agreed formatting conventions. While it might seem trivial, consistent formatting significantly eases code comprehension for others.

Code reviews are more than just a tool for bug-fixing. They're a vehicle for creating robust, accessible code and nurturing healthier, more inclusive work practices.

Cultivating a Code Review Culture in Academia: Bridging the Gap

Academic circles have long been a hotbed for ground-breaking ideas and innovations. However, when it comes to code review practices, academia has lagged behind the commercial and open-source software development sectors. This was the central theme of our second talk, led by Thibault Lestang.

The speaker emphasised the unique nature of research software, which sets it apart from other forms of software development. The software is typically developed within diverse contexts, often by individual developers and primarily for answering specific research questions. Consequently, the value of such software lies in the knowledge it facilitates rather than the software itself.

The speaker endorsed the use of a checklist to guide the review process. Such a list could include poor formatting, dead code, and missing documentation. This checklist serves as a guide, helping both the author and the reviewers navigate the review process effectively.

Effective communication is a cornerstone of a productive code review process. The ability to provide feedback in an understanding and supportive manner is essential. Feedback should be constructive, specific, and should ideally suggest alternatives. However, it's important to note that the process is not only technical but also social. Therefore, interactions during code reviews should harness an inclusive atmosphere rather than lead to exclusion.

The talk concluded by reinforcing the importance of top-down changes, where project managers drive and foster code review practices in academia. Research software development should adhere to high-quality standards for numerous reasons. It not only accelerates research but also drives inclusion, attracts and retains talent, and magnifies the impact of the research.

Navigating the Maze of Collaboration: A Key to Effective Code Reviews

The third session of our workshop tackled the often-difficult subject of designing code for collaboration, an aspect that bears significant implications for code reviews. Our presenter, Michal Grochmal, highlighted several crucial aspects that play pivotal roles in fostering effective collaboration: data-driven decision making, utilisation of Git for version control, comprehensive documentation, and, above all, a spirit of true collaboration. Each of these elements not only contributes to smoother teamwork but also lay the groundwork for more effective and constructive code reviews.

The premise was simple yet profound – how do we avoid stepping on our collaborators' toes while keeping the project on track? Everyone, at some point, has experienced the paradox where adding more people to a software development project seems to slow down the progress rather than speed it up. This problem, often referred to as the mythical man-month, hints at the complexities of collaboration in software development.

Perhaps the most important takeaway was the notion of not being overly precious about our code. In a truly collaborative environment, and especially during code reviews, we need to remain open-minded, and receptive to constructive criticism and alternative ideas.

Collaboration and Networking Opportunities

One of the core highlights of this workshop was the networking opportunities that were encouraged throughout the event. It brought together a diverse and vibrant group of participants - from RSEs to DH PhD students, seasoned software developers, and accomplished DH academics. Building a community of researchers and developers allows for a continuous exchange of insights and advice, paving the way for more innovative and effective solutions. It offers an environment where issues can be collectively addressed, and where questions can be shared. It also allows for the creation of supportive relationships and collaborations that can extend beyond the duration of the workshop.

In an effort to encourage open conversation and deeper connection, the workshop was designed to create an inclusive, collaborative atmosphere. It was not just about imparting knowledge but also about facilitating relationships and encouraging participants to share their experiences, their struggles, and their successes. Whether it was through Q&A sessions, or casual chats during breaks, participants were encouraged to interact and engage with each other. This not only enriched the overall experience of the workshop but also provided a platform for future collaborations, mentorship opportunities, and a lasting sense of community.

The Future of Code Reviews in Digital Humanities

Reflecting on the event, it is evident that code reviews can hold a critical role in DH research. It has highlighted that this practice not only aids in improving software quality but also facilitates greater transparency, encourages knowledge sharing, and promotes a culture of inclusivity and collaboration. Consequently, the workshop highlighted the value of integrating code review practices into the DH scholarship.

Going forward, one of the crucial steps we must take is advocating for the incorporation of code review practices among DH master and PhD students. By making code reviews a standard practice within the academic curriculum, we can encourage an essential shift in the research culture. Integrating code review practice into academia will align closely with the broader objectives of DH.

Regarding upcoming events, our focus will remain on further promoting code reviews and fostering an open dialogue about software development in DH scholarship. I plan to conduct another workshop, targeting both experienced researchers and those at the beginning of their academic journey. As we continue to advocate for the routine practice of code reviews, I'm hopeful for a future where high-quality, sustainable research software can be achieved with greater ease.