How to perform code review

Code review is an integral part of modern software de­vel­op­ment. Code review is carried out by other members in the pro­gram­ming team, and it should help uncover any errors and improve code quality. We’ll present the different tech­niques and ap­proaches in detail.

Code review is a quality assurance measure for software de­vel­op­ment. Source code is the fun­da­ment­al medium of de­vel­op­ment work and the primary product of pro­gram­ming. Newly created or modified code undergoes a code review. One or more team members review the pro­gram­mer’s work during this process.

A software project includes a 'code­base'. This is a col­lec­tion of code files which deliver a product. This includes the actual product code, con­fig­ur­a­tion, de­vel­op­ment 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 pro­duc­tion version of the codebase.

De­vel­op­ment usually takes place on feature branches, which are peri­od­ic­ally in­teg­rated 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 pro­duc­tion.

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 re­quire­ment. Beyond that, there are a variety of other quality criteria for clean code. The presence of comments, clarity and con­sist­ency of code, meeting style guidelines, and in­teg­rabil­ity into existing systems are all critical and are con­sidered during code review.

Since most de­vel­op­ment 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 de­vel­op­ment team. New members receive feedback on con­ven­tions and best practices, and knowledge is shared and dis­trib­uted within the or­gan­iz­a­tion. 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 ef­fi­ciency and ease the burden of small-scale and time-consuming co­ordin­a­tion. This allows the people involved to con­cen­trate on the actual code review.

Con­cep­tu­ally, code review by humans lies between two automated analysis methods, static and dynamic analysis. These are the dif­fer­ences 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 de­vel­op­ment team. They are known as 're­view­er­s'. The reviewers read the code and identify possible errors as well as de­vi­ations from the con­ven­tions es­tab­lished by the team. Either the reviewers improve the code after the review or they pass their findings on to the original authors, who in­cor­por­ate 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 com­mu­nic­ated to the reviewers? How are errors found and how are comments assigned to the ap­pro­pri­ate places in the code and made available to those re­spons­ible for im­prove­ment? This could only be co­ordin­ated within very small teams without special code review tools.

Code review is usually an integral part of the de­vel­op­ment process in dis­trib­uted and agile pro­gram­ming teams. Con­tinu­ous In­teg­ra­tion (CI) means that code is con­tinu­ously 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 in­teg­rated and sub­sequently played out to pro­duc­tion systems if all tests are passed.

Let’s take a look at the in­di­vidu­al 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 en­vir­on­ment
       
2. Integrate code into codebase
   1. Analyse and format code on feature branch auto­mat­ic­ally
   2. Perform code review and implement im­prove­ments
   3. Merge code into main branch
   4. Play out and test main branch on staging site
       
3. Putting code into pro­duc­tion
   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 de­vel­op­ment. Code review ensures that newly written code is as error-free as possible and meets the or­gan­iz­a­tion’s quality standards. This minimises technical debt in the long run and it prevents buggy code from running on pro­duc­tion systems in the short run.

Code is a powerful medium. Once written, the same code runs over and over again or sim­ul­tan­eously 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 pro­duc­tion system than to fix them before the code goes live.

Code review helps to even out quality dif­fer­ences between different parts of the codebase. This is because code quality varies greatly depending on the cir­cum­stances when the code is written. The following factors can lower the quality of the code de­vel­op­ment:

• Lack of pro­gram­ming ex­per­i­ence
• Little knowledge of the system
• Lack of fa­mili­ar­ity with team con­ven­tions
• Stress during de­vel­op­ment
• De­vel­op­ment under time pressure
• Mental ex­haus­tion

Code goes beyond writing programs nowadays. Code is an ex­press­ive medium which can be used to precisely describe all kinds of systems. For example, code is used to implement block­chain-based smart contracts or to define cloud en­vir­on­ments using In­fra­struc­ture as Code. A code review may also be carried out for these ap­proaches.

The best practices presented in this article come from a broad empirical study of a Cisco pro­gram­ming team by Smart Bear. In part, the best practices reflect the lim­it­a­tions of human reviewers. Code is a complex medium which requires a lot of attention when reviewing. A human has limited mental capacity which di­min­ishes under con­tinu­ous effort. Errors can be easily over­looked 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 re­spons­ib­il­it­ies 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 con­cen­tra­tion 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: An­nota­tions guide reviewers through and explain code changes.
   
• Use check­lists: These should include items to be con­sidered during each review.
   
• Establish a process to correct errors that are found: It is not enough to merely detect errors. Clear guidelines and struc­tures are required to correct errors.
   
• Promote a positive code review culture: Errors should not be presented as a personal fault, but as an op­por­tun­ity to learn.
   
• Leverage the sub­con­scious im­plic­a­tions of peer review: Pro­gram­mers put more effort into code when it is subject to peer review.
   
• Go for light­weight code review processes: Modern code review tools have made code review efficient.

Code review is con­sidered an essential part of software de­vel­op­ment. This is because the ad­vant­ages of code review are obvious. However, some dis­ad­vant­ages also arise from its usage. Let’s take a look at the ad­vant­ages and dis­ad­vant­ages of code review.

The primary advantage of code review is to detect and fix bugs before they have negative im­plic­a­tions. This is far more efficient than detecting and cor­rect­ing errors later in the code lifecycle. If faulty code is already part of a pro­duc­tion system, other com­pon­ents may build on it and it becomes more difficult to make changes.

The benefits of regular code reviews go beyond the search for in­di­vidu­al errors. In par­tic­u­lar, it is also important to look at the 'big picture'. How does the code fit into the codebase? Regular code reviews help to identify over­arch­ing patterns and to define standards. In addition to func­tion­al errors, code smells are iden­ti­fied and addressed. Re­fact­or­ing and design patterns can be used to create ho­mo­gen­eity across multiple com­pon­ents.

Code reviews involve the members of the pro­gram­ming team and bring them into dis­cus­sion with each other. Not sur­pris­ingly, es­tab­lished code review processes help increase the team's coding skills. Code reviews build and dis­trib­ute knowledge in the team and improve the code skills of in­di­vidu­al members.

Code reviews help establish a culture of quality at an or­gan­isa­tion­al level. A pro­gram­mer will generally make more effort if they know their own work is being reviewed. It is suf­fi­cient to submit about one third of the code created to a code review.

Of course, a code review means more effort for the or­gan­isa­tion. 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 con­sid­er­able costs.

Code review can be very in­ef­fi­cient without sup­port­ing code review tools. Tra­di­tion­al methods were prob­lem­at­ic before light­weight code review became popular. In any case, clear goals and ob­ject­ives for code review processes are needed. This makes effort and outcome cal­cul­able and avoids states of limbo.

Code reviews should result in an increase in knowledge and team cohesion for de­velopers. A con­struct­ive and collegial en­vir­on­ment is important. Hostility or ac­cus­a­tions can have a negative effect on those involved. Newcomers to the team, members of minor­it­ies and re­l­at­ively in­ex­per­i­enced pro­gram­mers are par­tic­u­larly affected by this.

The first form of code review was known as the “Fagan in­spec­tion”. 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 in­spec­tion is im­possible to integrate into modern agile de­vel­op­ment work.

In contrast to the tedious code in­spec­tion of Fagan, light­weight ap­proaches 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 de­vel­op­ment team (reviewer). In addition to looking for bugs, code struc­tures are discussed, and al­tern­at­ive ap­proaches are explained. The direct com­mu­nic­a­tion between the author and the reviewer enables quick feedback and im­prove­ments to be in­cor­por­ated im­me­di­ately.

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 de­vel­op­ment machine to be used. An 'over the shoulder' code review is straight­for­ward and can be carried out on an ad hoc basis.

Code review with pair pro­gram­ming is con­cep­tu­ally similar to 'over the shoulder' code review. Two members of the pro­gram­ming team are involved again. The dif­fer­ence 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 pro­gram­ming in­ter­twines the two processes.

One person, known as the 'driver', writes code and takes care of the im­ple­ment­a­tion details during pair pro­gram­ming. 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 per­spect­ives to take place, which ensures a power balance and gives both people the op­por­tun­ity to recover mentally. Fur­ther­more, the par­ti­cipant with less ex­per­i­ence 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 dis­cus­sion and the in­cor­por­a­tion 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 con­trib­ut­ors. 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 ef­fi­ciency and collect metrics. The tools make the review process plannable, con­trol­lable and veri­fi­able.

There is a wide range of available code review tools. Some of these are in­teg­rated into existing ap­proaches for Con­tinu­ous In­teg­ra­tion or Con­tinu­ous Delivery (CI/CD). We’ll present the different types of tools along with examples.

Dis­trib­uted 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 vis­ib­il­ity and emphasize teamwork. These platforms provide built-in code review before accepting new code using merge requests.

These tools use Git or another dis­trib­uted 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 es­tab­lished itself as the standard platform for the web-based man­age­ment of Git re­pos­it­or­ies. The primary mechanism for code review is the Pull Request. Follow a simple scheme to make changes to the re­pos­it­ory’s code:

1. Clone re­pos­it­ory as local copy
2. Make changes in your own branch
3. Create Pull Request: Ask the re­pos­it­ory main­tain­ers to review the changes and merge them into the master re­pos­it­ory if they pass.

The code review tool Review Board puts review requests in the fore­ground. The modern and friendly web interface provides an overview of all review requests in progress across re­pos­it­or­ies 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 pro­duc­tion codebase. Changes are reviewed by code review and will only go into pro­duc­tion if they pass. A Gerrit in­stall­a­tion includes a self-hosted Git en­vir­on­ment with SSH access and a web-based interface available using HTTPS. In addition to optional email no­ti­fic­a­tions, Gerrit includes a system for voting on code changes.

The code review tool Code Col­lab­or­at­or from Smart Bear puts user stories in the fore­ground. These are user-centric spe­cific­a­tions of func­tion­al­ity that are trans­lated into code and validated through testing. The tool involves the pro­gram­ming team, managers, and test teams, and enables con­sist­ent review of changes to user stories, code, and test plans.

These tools, known as 'linters', are used to auto­mat­ic­ally analyze and format code in pre­par­a­tion for code review. This is tech­nic­ally a static analysis because the code is read but it is not tested. Linters are used as part of the CI pipeline to stand­ard­ise the format­ting of code or to adapt the code to style spe­cific­a­tions.

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 in­jec­tions, and out of bounds errors.

These re­l­at­ively new tools function con­cep­tu­ally like a web-based code editor with syn­chron­ised changes between multiple users. They allow pair pro­gram­ming in dis­trib­uted en­vir­on­ments and enable 'over the shoulder' code reviews across geo­graph­ic bound­ar­ies. These tools have gained great pop­ular­ity in the wake of the Corona pandemic.

The web-based Replit and the LiveShare can be in­teg­rated with Microsoft’s editor VSCode and can be used as col­lab­or­at­ive HTML editors. Both tools can handle other languages and allow you to work col­lab­or­at­ively with multiple files and even run code.