A 2022 survey of 1000+ tech professionals from companies of all sizes found that 84 percent of businesses have a formalized process for code reviews. Out of these, 36 percent of the tech companies claimed that code reviews are the most remarkable technique to raise the quality of code.

Software engineers require efficient methods for writing, reviewing, and implementing consistently high-quality code. A thorough code review procedure can save the time and money wasted on faulty code, allowing engineers to work more productively and fostering a more effective team environment. With code review best practices, businesses can achieve a valuable and long-lasting competitive edge.

In this article, we will outline the best practices for code review and the impact of this procedure on productivity and timelines. Then, we will cover its incorporation into the development process and share some examples of successful code review implementation at Techstack,a software engineering company that follows best practices of code review, bringing high standards to the tech industry.

Best Practices for Code Review

Maslov’s pyramid of code review has five layers. Each of them is a characteristic to which the reviewed code must conform. The bottom layer is the correctness of the code, which is of prime importance. Code review shouldn’t proceed to upper layers until the bottom layer, correctness, gets approved.

According to this principle, the code reviewer moves on, layer by layer, checking if the code is: secure, readable, elegant, and altruist.

Maslov’s pyramid of code review

How to Prepare Your Code for Review

One of the best practices for code review is thorough preparation. An author should prepare the code for review far before the procedure itself. They should plan and write the code with the reviewer in mind, saving them time and effort as much as possible. What can the author do to prepare the code for review?

  • Automate whatever they can
  • Don’t do any “by-the-way” changes
  • Document code
  • Decompose code
  • Review the code themselves first

Automate Whatever You Can

Automation is one of the best code review practices. The time of software engineers is precious. Therefore, automate every repetitive action of the engineer. Here is what a code author can delegate to machines:

  • Style guide. It explains to a software engineer how to use a specific programming language. There are style guides for all programming languages. Therefore, there is no need to write them from scratch again for a new product.
  • Code smells. Any trait in a program's source code might point to a more significant issue. Code smells can be automated with static code analyzers in the cloud and local formats.
  • Security vulnerabilities. Understanding how a software developer opens data for others and what vulnerabilities it causes is essential. Automating vulnerability management helps to eliminate repetitive tasks prone to human error and replaces them with data-driven vulnerability prioritization.
  • Tests (unit, integration, end-to-end, etc.). All tests are already automated and can be run locally in various services and repositories. Many tools can run tests and analyze code, revealing the code coverage.

No “By-the-Way” Changes

In code review best practices, a software engineer writing the code shouldn’t make any “by-the-way” changes. This means that the engineer should follow their task strictly and not change anything in the code they were not supposed to.

For example, if the task is to change the value from “true” to “false,” the engineer should do it. However, if during the task completion, they noticed a typo or a function that was not working and decided to change or delete it. In that case, it may cause changes in various files and misunderstandings for their code reviewer.

It doesn’t mean that the engineer writing the code has no right to improve their work environment. It implies that every change has to be systematized and make perfect sense for other engineers working on the product. Every “by-the-way” change has to be done as a new task.

Document Code

When Eugene Zarashaw, a Facebook Engineering Director, was asked about the organizational structure of Facebook and how the organization works, he said, “Effectively, the code is its own design document often,” meaning that the way to write and comment on the code is how it gets documented.

Therefore, software engineers shouldn’t be afraid to comment on their code, add good naming and structure, and update documentation, such as MD files, Confluence, etc., for their colleagues who will maintain the code. It is essential to understand that when an engineer writes code in any programming language, it should be well-written and structured to explain how it works and how to run the functions.

Smaller is Better

The golden rule of code reviews best practices is preparing the code for a code review to keep all pull requests smaller than 500 business code lines. Business code lines mean the code that will be run, read, and maintained by other engineers. It doesn’t include comments, new lines, different types of parenthesis, and different code formatting.

A pull request over 500 business code lines makes it very complicated for a code reviewer to analyze the code. In that case, a reviewer may ask for additional meetings to get explanations from the engineer who wrote the code. To avoid any possible complications, it is essential to decompose the code as early as possible. We recommend doing it during the planning instead of the development phase.

Author is the First Reviewer

The engineer who wrote the code is its first reviewer. Before transferring the code to another software engineer, the code's author should review it critically, abstracting from the fact that it is their code. The author should pretend that the code was written by someone else and not make any concessions during the code review.

Before assigning a code reviewer, an author should read and understand the code. If any questions arise, the author should find the answers to all of them. The author can write down these questions and answers as comments to the code, especially if the answer refers not only to this pull request but to the entire code in general.

Review Time

Optimizing review time is one of the best practices for code review. Both an author and a reviewer should value their time and make as many preparations as possible. In this case, the review can be conducted as swiftly as possible.

Respect Each Other

Code review is not a battle where a reviewer has a chance to criticize or humiliate an author. Both an author and a reviewer should see a code review as an opportunity to grow and improve their codebase and the quality of the code. Therefore, both sides should show respect to each other.

Code review should never turn into a fight, but should remain a discussion. It should be the task-oriented work of two peers. A reviewer should always work with a code, not with its author. Reviewer’s comments shouldn’t sound like blame, but like a proposal. They need to explain why they propose specific changes in the code and how these changes will improve it.

Set Clear Goals

Now, having discussed the core principles of a code review, it’s time to go back to Maslow’s pyramid of code review and describe it layer by layer. The bottom layer of the pyramid—correctness—has the highest priority. Every pull request has to reach a clear goal. Software engineers should understand that they write code to solve a particular problem. The following questions will help determine if the code meets the set goals.

  • Does the code do what it is supposed to do?
  • Does it handle edge cases?
  • Is it adequately tested?
  • Is it performant enough for this use case?

Code Security

Security is the second layer of Maslow’s pyramid of code review. Every month, security breaches cause severe problems for organizations of all types and sizes. Only in the third quarter of 2022, due to data breaches, 15 million data records were exposed globally. Software engineers must understand the code's vulnerabilities and the security issues they must handle.

  • Does the code have vulnerabilities?
  • Is the data stored safely?
  • Is personal identification information handled correctly?
  • Could the code be used to induce a DOS?
  • Is input validation comprehensive enough?

Readability is a Must

A software engineer doesn’t write code for a machine to read it once and forget. Code is written to be read by a human, not by a computer. Other engineers will have to maintain, read, and understand the code for a long time. Therefore, readability is a critical layer of the code review’s pyramid. The code must be written clearly and reflect exactly what is written in the business requirements.

  • Is the code easy to read and comprehend?
  • Does it make clear what the business requirements are?
  • Are variables, functions, and classes named appropriately?
  • Do domain models map the real world to reduce the cognitive load?
  • Does it use a consistent coding convention?

Are You Proud of This Code?

When a reviewer approves the code, they take ownership of this code along with the author. Being proud of the code means wishing to share with your peers that you have worked on this code. It implies that the code is elegant, leverages well-known patterns, and handles the consistency between particular services and microservices.

What Improvements Does This Code Bring?

This question refers to the top layer of Maslow’s pyramid of the code review: altruism, a  selfless desire to work for the benefit of others. It is about evaluating the outcomes of a code review and addressing technical debt that prevents businesses from growing. This layer implies answering the following questions:

  • Does the codebase become better than it was?
  • Does it inspire other engineers to improve their code as well?
  • Does it make documentation/documentation coverage better?
  • Does it introduce better patterns of usage?
  • Does it solve some of the tech debts?

The Impact of Code Review on Productivity and Timelines

The code review process has an overall positive impact on productivity and timelines. It aids in increasing code quality, discovering defects early, and decreasing the time spent on quality assurance. Code reviews help minimize the number of flaws and inconsistencies that otherwise are discovered only after the product release.

Knowing that a colleague will review the code, an author is likelier to write clean and concise code. It boosts the author’s productivity and saves the reviewer’s time. With the best practices for code review, another pair of eyes can catch minor flaws and patterns in the early stages. Leaving comments in the code for a reviewer makes it easier to recognize edge instances and saves time in investigating the case.

Code review best practices give software engineering teams a framework for discussing each other’s works and proposing changes. Code reviews help to maintain a consistent codebase and compliance with all applicable standards, regulations, and style guidelines. Therefore, this process speeds up the onboarding of new software engineers who benefit from knowledge sharing fostered by code reviews.

Incorporating Code Review into the Development Process

Code review is usually performed immediately after the author has written the code. It is normally placed between the “in progress” and “QA” columns. Code review has the following lifecycle:

Best practice for code review

First review. The author should review their code themselves before assigning another software engineer to review it.

  • Code review demo. A code reviewer can request a code review demo to understand the code better. The code can be run during the CR demo to show the reviewer how it works.
  • Reject. A reviewer can reject the code, returning it to the “in progress” or “started” columns. Rejects can become a pitfall for the entire development team, increasing the time for feedback and the next iteration of code review. Therefore, the rejects should be prioritized.
  • Conflicts resolution. Conflicts arise betweenone ticket and other tickets at the moment of integration or merging to a particular environment. Tickets should always be updated and rebased to avoid conflict resolution. The joint work of engineers on interdependant tickets will help to find a consensus.

Examples of Successful Code Review

How To Delete a Non-Working Function Correctly?

If there is a need to delete a non-working function from the code, a review should make the following steps:

  1. Log the place with this function in the code.
  2. Run regression tests.
  3. Check if this code is indeed not used in the system.

What if the Author of the Code Asks for a Review to Improve Their Code Because They Lack Knowledge?

If the author added a to-do comment for a reviewer, “make the code better because I don’t know how to,” the reviewer should proceed accordingly:

  1. Reject the code.
  2. Offer help to the author and teach them how to proceed.
  3. Don’t make changes in the author’s pull request, but let them improve their code using the knowledge they gained.

What to Do if a Reviewer is not an Expert in this Business Domain?

  1. If possible, a reviewer should be assigned based on their experience and knowledge in the business domain. GitHub may yield reviewers with relevant experience.
  2. If it is not possible, an assigned reviewer should request a code review demo to better understand the context from the point of business and the service.

Excel in Your Code Quality with Techstack

Code review is an efficient method to achieve a consistently high quality of code. When performed following the best practices, this process helps your business save time and money otherwise spent on cleaning faulty code and fixing flaws and inconsistencies. Code reviews allow you to raise productivity and optimize timelines, giving your business a competitive edge in your industry.

Techstack is a full-stack software engineering company that follows the best code review practices to deliver high-quality standards of software product creation and make an impact on the world. Our software engineers have extensive experience creating intricate solutions and customizing the development process.

Contact us to talk to our expert about code review best practices.