Code-review.org is an online tutorial that helps impart best practices for reviewing code, responding constructively to feedback from others, and offering solutions using Github.

What are the goals?

The goals of the project are to enable everyone involved in scientific software to:

• Become a better reviewer. Reviewing is hard! We all need to take into account how to communicate constructive and actionable criticism. Practice reviewing in a no-consequence environment using the tutorial.

• Become more comfortable having your code reviewed. People may explain a scientific idea with a sketch on a whiteboard or a napkin with no problem. But when it comes to code, there is a tendency to keep the code hidden. You might have heard people say, “Oh, I need to polish this code before I show it to you.” There is some psychological effect behind this sentiment, and it would be great to change perspectives so that people feel comfortable showing even pseudo-code to one another. Sharing early and often can become second nature.

• Use code review as a collaboration tool. Use code review as part of onboarding new team members and collaborators. Share knowledge and know-how among team members. There is a real benefit to being on either side of a review. We’re trying to humanize this process and build rapport between people.

• Read more code than you write! Take a peek into your favorite open-source tools. Encourage people to have a look inside the software they are using. How does this code work? Why did the developers design the code in this manner?

• Enable more open-source contributors and more open-source reviewers. This is a lofty goal, but there are many people who would make really good software engineers, and they just don’t know it yet.

What are the learning outcomes?

Code review is a skill. You can break it down, you can practice, and you can improve. A difficulty is that developers are often learning a bunch of other skills at the same time as writing code -- the mechanics of git and Github (which can be tricky), maybe a new programming language. Maybe you are a scientist learning a new language, or maybe you are a software engineer learning new science. Perhaps you have to fit into a new team and its culture.

And this process never stops! Whether you are just starting out or are a seasoned professional, you are always learning something. And also you’re going to be learning the skill of code review.

As you work through the code review tutorial, you’ll practice the mechanics of Github: navigating issues, pull requests, adding comments and suggestions. You’ll have the chance to review the pull requests in the exercises, with some prompts to help you along.

You are not alone.

Code review can feel quite exclusionary. It can be a gatekeeping exercise, particularly for new contributors to open-source projects. There is no easy remedy to this situation, and it takes continued thought and effort within each team or community to find a dynamic that works well.

Building community and building great teams take time, skill, and dedicated effort. Luckily, you do not have to start from scratch!

If you are the only person writing code on your team, join a research software engineering (RSE) organization and find your people.

• US-RSE. A community of people who make research software happen.
  
• Society of Research Software Engineering which emerged from the successful grass-roots RSE movement and is the successor to the UK RSE Association.
  
• Better Scientific Software. A hub for scientific software development resources.
  
• Campus Champions. Uniting Research Computing Facilitators
• UCAR Software Engineering Assembly A community for software engineering professionals within UCAR.

Acknowledgement

This work was supported by the Better Scientific Software Fellowship Program, funded by the Exascale Computing Project (17-SC-20-SC), a collaborative effort of the U.S. Department of Energy (DOE) Office of Science and the National Nuclear Security Administration; and by the National Science Foundation (NSF) under Grant No. 2154495.

Author bio

Helen Kershaw is the Lead Software Engineer for the Data Assimilation Research Testbed, a widely used, open-source community software facility for data assimilation. Helen has a PhD in Mechanical Engineering from the University of Canterbury, New Zealand, and a Geophysical Sciences degree from the University of Leeds, UK. Helen has worked for a geophysical survey company that flew gravity and magnetic surveys, and worked for several years in the Center for Computation and Visualization at Brown University before joining NSF NCAR. Helen is interested in mentoring, community code, and RSE as a career path.