Effective Code Reviews For Remote Teams

In 2020 a large aspect of the landscape for modern application development changed. The result of an unexpected pandemic forced brick and mortar offices to close their doors and ask employees to perform their daily tasks remotely. This included teams of software engineers focused on creating, building, and enhancing the technology needs of their employer.

Asking team members to work remotely for a short period of time or even a portion of a week is one thing. Instantly pivoting and asking everyone to plan to work remotely indefinitely is another. In fact, the downstream effects of this new requirement stuck into the heart of any team's biggest need ... intra-team communication.

For the purpose of this article, I am going to narrow my focus to the very social aspect of peer reviews and focus on how to yield effective code reviews while working in a 100% remote situation.

Code Reviews Explained

So what is code review? According to Wikipedia, a code review is:

"Code review is a software quality assurance activity in which one or several people check a program mainly by viewing and reading parts of its source code, and they do so after implementation or as an interruption of implementation."

Code reviews are often referred to as peer reviews, pull-requests (PRs), and even a merge request. Regardless of the term used to define the process, the end result is the same - to ask another capable team member to review updates to the code base before pushing the changes to the next step of the development lifecycle.

Level Setting Code Reviews

Let there be no confusion, the goal of all code reviews should be to maintain quality in the underlying application or service under review. Years ago the Ford Motor Company initiated the “Quality is Job 1” marketing slogan, which can be applied to code reviews. After all, no product owner wants to receive feature code that hasn’t been inspected from a quality perspective.

There are three additional benefits which often result in employment of code reviews:

• learning opportunity
• the feedback ladder
• software engineer analytics

Learning Opportunity

Code reviews should always be considered a learning opportunity for everyone involved. In most cases, the more senior reviewer will provide alternatives or suggestions which lead to improvements to source code and convey a lesson to the submitter. However, it is also common for the reviewer to gain knowledge as part of the process. In fact, it was in a code review that I learned the use of underscores is allowed in Java for setting static variables:

private static final long FIFTEEN_MILLION = 15_000_000;

The Feedback Ladder 

The “Ladder of Feedback” was developed by Daniel Wilson (Harvard Project Zero) and is a protocol or structure that establishes a culture of trust and support by sequencing feedback in an order that is constructive. Netlify applied this cognitive approach to code reviews and established the Feedback Ladder:

Understanding that no two developers solve problems exactly the same, code reviews can quickly become filled with suggestions that are less about code quality and code preference. While the suggestions may be valid, they do not resolve a negative situation with the code being reviewed.

The Feedback Ladder approach allows reviewers to prefix suggestions with one of the following categorizations:

• [mountain] – code review blocked until comments are addressed
• [boulder] – blocking, but can be allowed to move forward (with a remediation plan)
• [rock] – not blocking, but future work is required (reference to ARM ticket in code)
• [pebble] – not blocking, requires future consideration
• [sand] – not blocking, “take it or leave it”

Note: the original Netlify design by Leslie Cohn-Wein uses the mountain, boulder, pebble, sand, and dust categories, but I have had better success using the categories provided above.

Software Engineer Analytics

The code review process itself provides an opportunity to gain analytical information on software engineers participating in the lifecycle event. Such information can be helpful to justify decisions that need to be made as a result of periodic performance reviews.

For the code reviewer who is consistently focused on following design standards and delivering quality, a manager can pull numerous examples to justify merit increases to upper management.

Conversely, an individual who is not the best fit for the team can be exposed over time via the code review process. While this is a situation that no one desires to be in, having the documentation available does help management make the best decision for their organization – without asking peers to spend time compiling their thoughts.

Code Reviews in a Remote-Driven World

Since working remotely, I have seen the following flow produce positive results with respect to code reviews:

• Create – utilize git-based tooling to establish a new code review
• Document – go the extra mile to include detailed information to supplement the code review (including diagrams and video links)
• Collaborate – using screen share or team-based tool, walk through the details of the code review
• Adapt – make the necessary updates, based upon feedback (the Feedback Ladder)
• Merge – complete the code review process (upon approval)

Communicate is at the center of this flow, meaning every step employs a communication strategy to not only keep the code review active, but as a mechanism to alert additional teams working on the same application or component. Some examples include:

Send direct links to code review (instead of email)Announce when the code review has been approved and updates are availableProvide information regarding the code which has been approved

Heroku Review Apps Feature

The Heroku ecosystem includes a feature called “Heroku Review apps” that will execute the code in any GitHub pull request (a form of code review) in a complete, disposable Heroku app. Review apps each have a unique URL that can be shared, making them a great way to propose, test, and merge changes to your code base.

The benefit to this approach is that the reviewer assigned to the code review can focus their efforts on the Heroku Review app running – saving them from having to stash in-progress changes in order to see a working version of the proposed source code. 

To utilize Heroku Review apps, simply navigate to the Deploy tab of the Heroku Dashboard:

Upon following the steps documented here, the Conversation tab in the GitHub pull request will show the Heroku Review app has been deployed:

This information is also available in the Heroku Dashboard in the Review Apps section of the application’s Pipeline page:

Conclusion

For me, 2020 was really no different than the last four years. I have been working exclusively in a 100% remote mode and even published the following articles on DZone:

• Code Reviews — What Really Matters?
• How Are Your Pull Requests?

My current project is by far the most complicated project I have worked on in an IT career that started in early 1992. In addition to a complex need that is getting filled, there are eight agile teams working on the project with staff located not only in North America, but Europe and Asia as well.

Considering the amount of progress that has been achieved in a fraction of the time that was required to create the original application, I feel strongly that our success is directly tied to the freedom of working remotely and being able to effectively communicate across vast geographical regions. This translates to highly successful code reviews using many of the suggestions provided above.

The code review process is only as isolated as an individual desires – with technologies in place to ease any gaps that were introduced in 2020. I truly believe code reviews have only improved as a result of a 100% remote scenario.

Have a really great day!