How to perform code review

Code review is an integral part of modern software development. Code review is carried out by other members in the programming team, and it should help uncover any errors and improve code quality. We’ll present the different techniques and approaches in detail.

Code review is a quality assurance measure for software development. Source code is the fundamental medium of development work and the primary product of programming. Newly created or modified code undergoes a code review. One or more team members review the programmer’s work during this process.

A software project includes a 'codebase'. This is a collection of code files which deliver a product. This includes the actual product code, configuration, development tools, tests, and more, all displayed in code. The entire codebase is managed with a version control system such as Git. Multiple 'branches' can be used to manage multiple versions of the codebase. This allows new features to develop and progress without changing the production version of the codebase.

Development usually takes place on feature branches, which are periodically integrated into the main branch. Code review is performed before the 'merge', i.e. before new or modified code is merged with the existing codebase. The goal is to detect and eliminate errors at an early stage before the code goes into production.

Weeding out bugs is not the only benefit of code review. The code working, i.e. running without any errors and achieving the desired result, is only a basic requirement. Beyond that, there are a variety of other quality criteria for clean code. The presence of comments, clarity and consistency of code, meeting style guidelines, and integrability into existing systems are all critical and are considered during code review.

Since most development work takes place in groups, the benefits of code review go beyond pure code quality. There are social benefits as code review is performed by other members of the development team. New members receive feedback on conventions and best practices, and knowledge is shared and distributed within the organization. Code review helps to cultivate a culture of quality.

The code review processes are usually supported by special code review tools, even if code review is performed by humans. Code review tools aid efficiency and ease the burden of small-scale and time-consuming coordination. This allows the people involved to concentrate on the actual code review.

Conceptually, code review by humans lies between two automated analysis methods, static and dynamic analysis. These are the differences at a glance:

The concept of a code review is simple. A modified or rewritten code is checked by one or more members of the development team. They are known as 'reviewers'. The reviewers read the code and identify possible errors as well as deviations from the conventions established by the team. Either the reviewers improve the code after the review or they pass their findings on to the original authors, who incorporate the changes.

Although the idea is simple, there is an extensive amount of effort required for code review. The devil is in the details. Which changes belong together and how are they communicated to the reviewers? How are errors found and how are comments assigned to the appropriate places in the code and made available to those responsible for improvement? This could only be coordinated within very small teams without special code review tools.

Code review is usually an integral part of the development process in distributed and agile programming teams. Continuous Integration (CI) means that code is continuously written, tested, and merged into the existing codebase. Code review by a human is part of the automated CI pipeline which each unit of code goes through. The code is integrated and subsequently played out to production systems if all tests are passed.

Let’s take a look at the individual steps of a CI pipeline and the position of the code review in it:

1. Write code
   1. Writing Code on Feature Branch
   2. Test code in local environment
       
2. Integrate code into codebase
   1. Analyse and format code on feature branch automatically
   2. Perform code review and implement improvements
   3. Merge code into main branch
   4. Play out and test main branch on staging site
       
3. Putting code into production
   1. Merge code into release branch
   2. Play out the release branch on the live site

Code review is an important part of quality control in software development. Code review ensures that newly written code is as error-free as possible and meets the organization’s quality standards. This minimises technical debt in the long run and it prevents buggy code from running on production systems in the short run.

Code is a powerful medium. Once written, the same code runs over and over again or simultaneously as multiple instances. Small errors in a central location will have a large impact on the overall system and will lead to a 'ripple effect'. As a result, it is usually far more costly to fix bugs in code that are already running in the production system than to fix them before the code goes live.

Code review helps to even out quality differences between different parts of the codebase. This is because code quality varies greatly depending on the circumstances when the code is written. The following factors can lower the quality of the code development:

• Lack of programming experience
• Little knowledge of the system
• Lack of familiarity with team conventions
• Stress during development
• Development under time pressure
• Mental exhaustion

Code goes beyond writing programs nowadays. Code is an expressive medium which can be used to precisely describe all kinds of systems. For example, code is used to implement blockchain-based smart contracts or to define cloud environments using Infrastructure as Code. A code review may also be carried out for these approaches.

The best practices presented in this article come from a broad empirical study of a Cisco programming team by Smart Bear. In part, the best practices reflect the limitations of human reviewers. Code is a complex medium which requires a lot of attention when reviewing. A human has limited mental capacity which diminishes under continuous effort. Errors can be easily overlooked without full attention being given and this wastes time.

The best practices aim to ensure that code review processes are goal oriented. If errors are found, they must be corrected. This requires clear responsibilities and ways to manage the processes and monitor progress. Let’s take a look at an overview of the best practices we found:

• Check a maximum of 400 lines of code per session: With larger amounts of code, errors are easily missed.
   
• Do not review more than 500 lines of code per hour: Otherwise, the reviewers’ ability to detect errors suffers.
   
• Limit code reviews to a maximum of 60 minutes: The reviewers lack the necessary concentration with longer code reviews.
   
• Set goals and capture metrics: How many defects are found per unit of time or per line of code?
   
• Code authors should annotate source code prior to review: Annotations guide reviewers through and explain code changes.
   
• Use checklists: These should include items to be considered during each review.
   
• Establish a process to correct errors that are found: It is not enough to merely detect errors. Clear guidelines and structures are required to correct errors.
   
• Promote a positive code review culture: Errors should not be presented as a personal fault, but as an opportunity to learn.
   
• Leverage the subconscious implications of peer review: Programmers put more effort into code when it is subject to peer review.
   
• Go for lightweight code review processes: Modern code review tools have made code review efficient.

Code review is considered an essential part of software development. This is because the advantages of code review are obvious. However, some disadvantages also arise from its usage. Let’s take a look at the advantages and disadvantages of code review.

The primary advantage of code review is to detect and fix bugs before they have negative implications. This is far more efficient than detecting and correcting errors later in the code lifecycle. If faulty code is already part of a production system, other components may build on it and it becomes more difficult to make changes.

The benefits of regular code reviews go beyond the search for individual errors. In particular, it is also important to look at the 'big picture'. How does the code fit into the codebase? Regular code reviews help to identify overarching patterns and to define standards. In addition to functional errors, code smells are identified and addressed. Refactoring and design patterns can be used to create homogeneity across multiple components.

Code reviews involve the members of the programming team and bring them into discussion with each other. Not surprisingly, established code review processes help increase the team's coding skills. Code reviews build and distribute knowledge in the team and improve the code skills of individual members.

Code reviews help establish a culture of quality at an organisational level. A programmer will generally make more effort if they know their own work is being reviewed. It is sufficient to submit about one third of the code created to a code review.

Of course, a code review means more effort for the organisation. The code review costs time and resources are also needed to control the processes involved. However, the costs incurred increase code quality. Remember that a lack of code quality will lead to considerable costs.

Code review can be very inefficient without supporting code review tools. Traditional methods were problematic before lightweight code review became popular. In any case, clear goals and objectives for code review processes are needed. This makes effort and outcome calculable and avoids states of limbo.

Code reviews should result in an increase in knowledge and team cohesion for developers. A constructive and collegial environment is important. Hostility or accusations can have a negative effect on those involved. Newcomers to the team, members of minorities and relatively inexperienced programmers are particularly affected by this.

The first form of code review was known as the “Fagan inspection”. This was an elaborate process which required four people and involved printing out the code on paper and several meetings. While this was effective at finding bugs, the Fagan inspection is impossible to integrate into modern agile development work.

In contrast to the tedious code inspection of Fagan, lightweight approaches to code review are used today. These involve the code’s author(s) and one or more reviewers.

The 'over the shoulder' method is the simplest form of code review. The author presents the written code to another member of the development team (reviewer). In addition to looking for bugs, code structures are discussed, and alternative approaches are explained. The direct communication between the author and the reviewer enables quick feedback and improvements to be incorporated immediately.

The 'over the shoulder' code review takes place on site at your own computer. The colleague looks over your shoulder while you present the code. This allows all resources and tools on the development machine to be used. An 'over the shoulder' code review is straightforward and can be carried out on an ad hoc basis.

Code review with pair programming is conceptually similar to 'over the shoulder' code review. Two members of the programming team are involved again. The difference lies in the timing of the code creation and code review processes. 'Over the shoulder' code review occurs after the code is created and pair programming intertwines the two processes.

One person, known as the 'driver', writes code and takes care of the implementation details during pair programming. The other person, known as the “reviewer”, monitors the written code and provides feedback. The reviewer also keeps an eye on the “big picture”: The code must not only be error-free and work on its own, but it must also follow the patterns and rules across projects.

It is important that the driver and reviewer regularly swap roles. This enables a change of perspectives to take place, which ensures a power balance and gives both people the opportunity to recover mentally. Furthermore, the participant with less experience is given the chance to learn in both roles.

Changes to code or the addition of new code on larger projects often requires code review by multiple people. The code review by email roundup consists of sending an overview of the changes to everyone involved. This is followed by several rounds of email discussion and the incorporation of changes until the review is complete and the code is finalised.

This process is likely to quickly become confusing with a large number of contributors. Therefore, Email roundup code review works best with the support of code review tools.

Modern code review involves the use of special code review tools. These tools structure the review processes, create efficiency and collect metrics. The tools make the review process plannable, controllable and verifiable.

There is a wide range of available code review tools. Some of these are integrated into existing approaches for Continuous Integration or Continuous Delivery (CI/CD). We’ll present the different types of tools along with examples.

Distributed version control systems (DVCS) and Git form the basis of code review tools. They include the features to track changes to the code and make them visible as 'diffs'. Platforms built on Git, such as GitHub and GitLab, improve visibility and emphasize teamwork. These platforms provide built-in code review before accepting new code using merge requests.

These tools use Git or another distributed version control system (DVCS). A web-based user interface is usually used to organise code reviews in the team. Some code review tools also have their own command line interface (CLI).

GitHub has established itself as the standard platform for the web-based management of Git repositories. The primary mechanism for code review is the Pull Request. Follow a simple scheme to make changes to the repository’s code:

1. Clone repository as local copy
2. Make changes in your own branch
3. Create Pull Request: Ask the repository maintainers to review the changes and merge them into the master repository if they pass.

The code review tool Review Board puts review requests in the foreground. The modern and friendly web interface provides an overview of all review requests in progress across repositories and branches. The rbt command provides quick access from the command line. In addition to code, graphics and PDF documents can also be included in the review processes.

Gerrit is set up on its own server and acts as an interface between changes to the code and the production codebase. Changes are reviewed by code review and will only go into production if they pass. A Gerrit installation includes a self-hosted Git environment with SSH access and a web-based interface available using HTTPS. In addition to optional email notifications, Gerrit includes a system for voting on code changes.

The code review tool Code Collaborator from Smart Bear puts user stories in the foreground. These are user-centric specifications of functionality that are translated into code and validated through testing. The tool involves the programming team, managers, and test teams, and enables consistent review of changes to user stories, code, and test plans.

These tools, known as 'linters', are used to automatically analyze and format code in preparation for code review. This is technically a static analysis because the code is read but it is not tested. Linters are used as part of the CI pipeline to standardise the formatting of code or to adapt the code to style specifications.

Static analysis also provides code metrics such as the number of lines of code (LOC) per file, class, or function. Linters can also detect common errors before human code review. These include typing errors, SQL injections, and out of bounds errors.

These relatively new tools function conceptually like a web-based code editor with synchronised changes between multiple users. They allow pair programming in distributed environments and enable 'over the shoulder' code reviews across geographic boundaries. These tools have gained great popularity in the wake of the Corona pandemic.

The web-based Replit and the LiveShare can be integrated with Microsoft’s editor VSCode and can be used as collaborative HTML editors. Both tools can handle other languages and allow you to work collaboratively with multiple files and even run code.