Increasing the confidence of first time open-source contributors and humanizing the process of code review
Code review is a skill. Currently there is literature available to read about code review, but not many hands-on tutorials, particularly for people outside of computer science. In contrast, there are a host of excellent ‘learn-by-doing’ online resources for learning programming languages. Moreover, code review circumstances can be challenging due to the nature of scientific coding. Researchers are often working on a new scientific problem while trying to learn git, GitHub, and a programming language, and during a code review session, their code may be ‘criticized’. Also challenging is the circumstance when scientific software developers start work in a new domain where they have little knowledge. During a code review session, it can be very difficult to separate criticism of the code from criticism of the person. This is a skill for both the reviewer and the reviewee always to be working on.
BSSw Fellow Helen Kershaw is creating a code review tutorial that can be done in pairs or individually; it can be used as a tool to onboard new contributors and as a refresher course for seasoned professionals. The tutorial will build from a text-based (no code) example to separate coding from the skill of reviewing and will include a soft skills section with examples of good, bad, and ugly review comments. Code review examples will focus on Python and Fortran---languages widely used in the geosciences. The tutorial will be extensible, so that people can provide feedback and add examples from their own domains and experience. The ‘learn-by-doing’ tutorial will use GitHub actions to create example code reviews, where people can make mistakes in a no-consequence environment.
Helen Kershaw is a Software Engineer at the National Center for Atmospheric Research. She works on the Data Assimilation Research Testbed (DART), an open-source community facility for ensemble data assimilation. Helen previously worked at Brown University at the Center for Computation and Visualization, where she led a team of research software engineers. She was a 2019-2020 XSEDE Campus Champion Fellow and is active in the US-RSE community.
Selected Resources
Code Review tutorial website Scientific Software Reviewers GitHub Organization BSSw.io blog article - Code-Review.org: An Online Tutorial to Improve Your Code Review Skills
