Code Review Workflow
Contents
Code Review Workflow#
Here’s a high-level view of a workflow researchers can follow to make code review part of their development process.
Find a reviewer#
There is no code review without a reviewer or reviewers. The good news is, almost any researcher who codes is a good candidate for being one.
Potential reviewers are not far: in your own research group, others you collaborate with or your local Research Software Engineering group. They can also be found in communities outside your institution or specific research domain. In the Find a reviewer phase, we look at different pools of potential reviewers, what makes a suitable reviewer, and ways of getting in touch.
Meet and agree on objectives#
A code review can improve code in a lot of different ways, but trying to do everything at once is rarely effective. In the Meet and agree on objectives phase, participants make it clear to others people involved why they are are pariticpating.
The goal of this second phase is for all the participants to agree on the purpose of the review. This is critical to a constructive and useful discussion during the actual review process. Key questions are:
What is the author expecting from the review?
What should the review enable? Better readability? Knowledge transfer? Better performance?
What part of the code should we look at?
Perform code review#
This is the core of the process. The code author and reviewer(s) meet (in person or virtually) to discuss the code. Although the subject is technical, everyone involved must remember that they are interacting with humans. Empathy, humbleness and non-confrontational communication are key to a successful code review.
The Perform code review phase is an iterative process, itself made of 5 phases:
Code author communicates the code and its context to reviewer(s) in advance and with context.
Reviewer(s) review code in light of objectives and areas of focus, agreed upon during the Meet and agree on objectives phase.
Author and reviewer(s) meet and discuss the code.
Code author implements changes.
Rinse and repeat.
Finish#
Ideally, the code review cycle ends when both the code author and reviewer(s) agree that the objectives set in the initial meetings have been met. In case both parties do not agree, the code author has decision power on whether or not to end the code review process.