Best Code Review Techniques

https://www.awesomecodereviews.com/code-reading/code-review-techniques/

Systematically reviewing source code is an essential part of ensuring code quality and correctness of the code. Yet, most developers review their code ad hoc, which means they do not have any formal, or even explicit code review approach that they can easily describe. While a few formal code review techniques exist, they are not widely known. In this article, I show you different code review techniques you can use to make your code review approach more systematic, explicit, and effective. Those techniques are either dedicated code review techniques, or techniques from other development disciples, such as code reading, testing, or debugging, that I adapted to facilitate the task of code reviewing to help you find more bugs, and understand the code under review better.

Modern code review is ad-hoc

Most programmers review code in an ad hoc manner. This means there is no explicit, formal, or systematic process that the team agreed upon to review code. Instead, the developers intuitively review source code files based on their experience.

Which files, methods and even statements developers look at, and in which order, is up to the individual developer, and often even up to their current mood. Similarly, which aspect or issues they look for in code is not well defined, and can change from developer to developer.

Junior developers struggle without concrete review techniques

While programmers develop their individual techniques for code reviewing over time, those techniques are implicit, vary from person to person, and often only live in the developers’ heads. Junior developers therefore often wonder how exactly they should review code, and what to look for. They learn how to review code by copying and mimicking what they see their peers do in code review. However, this process to learn code reviews is neither efficient nor effective. It also means that each team member will have a slightly (or vastly) different approach to review code.

Transforming implicit to explicit knowledge

One of the best code review hacks a team can embrace is to transform the implicit knowledge that experienced developers on their team have (basically in their head), into explicit knowledge.

During such a transformation process, the experienced developer describes in detail what they do during a code review. Over time, those explicit guides to reviewing code, can become one overall guideline that describes how code is reviewed within a team. Such a guideline serves two purposes: First, it streamlines how a team reviews code, and second, it allows people new to the team to learn quickly what is important during code reviewing.

Formal, systematic, and explicit review techniques

In addition to learning from the experience of senior developers, we can also learn from formal, systematic, and explicitly described techniques for code inspection, code review and code reading.

In this blog post, I show you some of the code review techniques I also teach in my code review workshops. This can help you to transform your implicit and ad hoc reviewing techniques into explicit and more systematic approaches.

Systematic Code Review Approaches

We will look at the following systematic code review approaches:

1. Checklist-based Code Reviews

One of my favorite code review techniques involves using a checklist. They are by far the most widely used systematic code review technique because the approach is straightforward to implement and does not involve a lot of additional effort. In empirical research, checklist-based code reviews have also been shown as very effective.

Checklist-based code reviews involve using a predefined list of items or criteria to assess the code. A checklist can focus on a variety of factors such as coding standards, design principles, security guidelines, and performance considerations. You can find a code review checklist that covers a wide range of topics here. Sometimes, only one of those factors, for example, security, is the focus of such a checklist. This makes sense when you want to perform a more thorough review in this specific area. Have a look at this security-focused code review checklist as an example.

Pros:

Provides a systematic and structured method for reviewing code, ensuring consistency and thoroughness.
Helps reviewers focus on important aspects that might be overlooked otherwise.
Assists in educating new team members about coding standards and best practices.
Functions as a memory aid, ensuring important aspects are checked.

Cons:

Correct usage of the checklist might be unclear or confusing.
Aspects not covered by the list might be overlooked.
May lack flexibility, as not all checklist items are applicable to every piece of code.
It might be not clear where to look, as no order for inspection was given.

Learn more about checklist-based reading here.

2. Test-Driven Code Reviews

During test-driven code reviews, the code reviewer starts by reviewing the test code before they review the production code. The rationale behind this approach is to use the test cases as use cases that explain the code. Thus, the code reviewer learns about the production code when they look at the test code, which helps them create a mental model. The tests are used as a specification of what the software is supposed to do, and the code reviewer learns about the assumption the code author had about the code through the tests.

Pros:

Helps improve the test code quality and thus maintainability and quality of the code.
Ensures high test coverage and quality.
Encourages writing meaningful tests that truly validate the code.
Tests can help the developer understand the production code.

Cons:

Depends heavily on the quality of the tests themselves.
Can’t be done in the absence of tests.
Tests might replicate the misunderstandings of the code author about the code’s specification.

Learn more about test-driven code reviewing here.

3. Bottom-up and Top-Down Code Reading

All code reading techniques can be broadly categorized also into bottom-up or top-down reading. Most of the time, we use a combination of those two approaches. So, let’s have a more detailed look!

Bottom-up Code Reading

Bottom-up reading means that the developer starts reading, understanding, and reviewing small fragments of the code first. Based on those small fragments, like single code statements, or small methods the developer works their way up to understand and evaluate more and more of the functionality and quality of the software under review. This way, the developer gradually builds a picture of how code elements interact to form the larger system.

Bottom-up code reviewing works well when reviewing a small, self-contained piece of code, like a function or a class. On the other hand, it also works well, when you have to review a larger piece of software you are completely unfamiliar with that lacks documentation.

Pros:

Developers build a thorough understanding of the nitty-gritty details of the code.
Helps to effectively identify local issues, bugs, and inefficiencies.
The developer needs less overall context about the system, making it suitable for new team members or for reviewing isolated components.
Works well for unclear or unfamiliar legacy code, or code that isn’t documented.

Cons:

It is a time-consuming approach due to the focus on details.
Reviewers might miss the big picture, as well as architectural or higher-level design problems.
When confronted with a large code change, starting at the lowest level can be overwhelming and inefficient.

Top-down Reading

In a top-down reading approach, the software developer starts by reading, for example, a user story or the documentation of the software first. These often non-code artifacts already explain the purpose of the code under review and give the reviewer an overview of what to expect. Then, the reviewer examines the overall structure and components of the systems. The goal is to build a mental model of the system before looking at the code in more detail. In a later step, the reviewer tries to find the most significant method(s), that drive the functionality and starts reviewing in more detail from there.

Pros:

This approach helps build an understanding of the system’s architecture and high-level design.
It is effective in spotting problems with the overall design, structure, and integration points.
The approach is suited for larger code changes or even complete codebases.
It helps prioritize which parts of the code to focus on for a more detailed review.

Cons:

Reviewers using only a top-down approach might overlook specific low-level coding issues or bugs.
Requires the reviewers to have a good understanding of the overall system, which might not be feasible for newcomers.
By examining only high-level artifacts, the reviewer might make incorrect assumptions about how high-level designs are implemented at the lower levels.

Learn more about top-down code reviews here.

Combining bottom-up and top-down code reviewing

In practice, a combination of both approaches is often used. Starting with a top-down review helps understand the system’s architecture and major components, setting the stage for a more detailed, bottom-up review of specific areas of interest or concern. This combined approach ensures the architectural integrity and the detailed correctness of the code.

4. Control-flow and Data-flow Code Reviews

Two other complementary code review approaches are control-flow and data-flow code reading. Control-flow reading follows the execution of the program, whereby during data-flow reading you follow the data.

Control-flow Code Reviews

Control-flow reading focuses on understanding how the program’s execution progresses. It examines the order in which statements, instructions, or function calls are executed and how the program moves from one part to another. This includes looking at loops, conditional statements, function calls, and recursion. Control-flow driven code reviews are great for finding logical errors.

Pros:

Highly effective in spotting logical problems with the flow of execution, such as loops, conditionals, and sequence of operations.
Essential for understanding the execution order and for debugging issues like infinite loops or unexpected branches in logic.
Helps in understanding the overall structure of the program, particularly the execution order and the interrelation of various components.

Cons:

Reviewers might miss issues related to data handling or data integrity.
It is less effective for data-intensive applications.
Complex to perform in event-driven systems due to the non-linear progression of execution.

Data-Flow Code Reviewing

Data-flow reading focuses on how data moves through the program. This includes tracking the source, use, and modification of variables and data structures, understanding how data is passed between functions, and examining how data state changes over time. Data-flow code reviewing is particularly useful when looking at the code with a security lens. It helps identify data leaks or points where sensitive data might be compromised.

Pros:

Effective in identifying problems related to data handling, such as data corruption, improper use of data structures, and issues with data lifecycle.
Particularly useful for uncovering security flaws that stem from the misuse of data, like buffer overflows or injection attacks.
Helps in tracing how data moves through the system, which is crucial for understanding complex interactions and dependencies.
Can identify inefficiencies in how data is processed, leading to opportunities for performance optimization.

Cons:

Tracing data flow can be challenging, especially in large codebases with numerous data paths and interactions.
Requires a detailed and thorough examination of how data is handled, manipulated, and transformed, which can be time-intensive.
Focusing primarily on data flow can lead to overlooking issues related to control flow, such as logic errors or incorrect program sequencing.

Combining control-flow and data-flow code reviewing

In practice, both control-flow and data-flow reading modes are often used together during code review. Understanding how data is handled (data-flow) is crucial for evaluating the logic and sequence of operations (control-flow). For example, in a function with complex logic, you might use control-flow reading to understand the sequence of operations while simultaneously using data-flow reading to see how data is manipulated throughout those operations. This integrated approach provides a comprehensive understanding of the code, helping to identify both logical errors and data-related issues.

Code Reading, Debugging and Program Understanding techniques

While reviewing code, we can make use of general code reading, debugging and program comprehension techniques. In the following, I’ll briefly highlight some of the most useful techniques.

5. Pattern Recognition

During pattern recognition, the code reviewer uses mostly a top-down approach to identify common patterns in the code. Such patterns include design patterns, algorithmic patterns, or idiomatic expressions in the programming language. Pattern recognition during code reviewing is helpful to create a mental model of the software system, but also to identify problems with the software’s architecture, or the design of algorithms.

Pros:

Helps create a mental model of the code change and the structure of the code.
Streamlines the review process and leads to more consistent review approaches even amongst different team members.
Well suited to find problems within the software architecture or design.

Cons:

Due to the focus on patterns, reviewers might overlook other problems.
Using known and common patterns to judge code, can bias the reviewers and they might dismiss good, new approaches, just because they are not established yet.
Reviewers need a broad knowledge of patterns and anti-patterns to look for.

6. Cross-Referencing

During cross-referencing, the code reviewer systematically reviews the dependencies and relationships between code elements, such as classes, functions or variables. This approach is suitable to understand the interdependencies and also the impact change can have on the system. As manual cross-referencing is a tedious task, code reviewers can use tools to extract, display or visualize this information. Most IDE’s provide built-in tools that help with cross-referencing, which is also often used during code refactoring. These tools build an index of all code elements and link them, which helps during navigation.

Pros:

Finds dependencies, and relationships and reveals how a change impacts the rest of the system.
Allows the reviewer to build a deep understanding of the codebase, and the code change under review.
Reviewers get a good understanding of the control flow and the data flow, thus allowing them to identify errors in execution and data manipulation.

Cons:

If done manually, cross-referencing is tedious and error-prone.
For larger code changes and systems might be overwhelming for the reviewer.
Focusing too much on relationships and dependencies between artifacts can lead to overlooking other issues.

7. Change-Impact Analysis

During change-impact analysis, the reviewer gathers information to be able to judge how the code change will impact the rest of the system.

While cross-referencing can be used as part of a change-impact analysis, a change-impact analysis is broader and also involves analyzing more high-level artifacts, such as specifications, documentations to understand the impact of the code change. A reviewer will normally start by understanding the rationale behind the code change, and its description (top-down). Then, the reviewer will identify affected components, analyze the dependency graph and assess the impact of this change on the functionality of the overall system. During such an analysis the reviewer should also look at the impact on the test system: does it need tests to change, or the be added?

Pros:

Discussions on the impact of code changes can improve the understanding a team has of the overall codebase.
Allows to direct reviewing efforts towards impacted and high-risk parts of the codebase.
Reduces the risk of introducing bugs or regressions.

Cons:

Change impact analysis can be very time-consuming.
The reviewer has to have already a good and deep understanding of the codebase to understand the impact.
It can lead to analysis paralysis, because the reviewer cannot completely envision all potential

impacts of this code change, and is thus reluctant to approve it.

8. Trace-Based Code Reading

Trace-based reading, often used during debugging, involves following the execution of code at runtime. The code reviewer can do this by stepping through the code in a debugger or by examining logs or output traces.

Most code reviewers use a static control-flow approach to review code, instead of this dynamic code analysis technique, that focuses on understanding how the code behaves at runtime.

This dynamic evaluation is useful when the code reviewer is puzzled by a certain part of the program, or expects a bug. It allows us to understand the state of the program at various points of execution, to track the sequence of function calls, and to observe changes in variable states over time.

Pros:

Allows the review to see how the system behaves at runtime.
Effective during diagnosing or evaluating “potential” bugs and problems.
Helps build a mental model of the code, thus helpful if the reviewer is unfamiliar with the system.
Can help catch side effects or anomalies that cannot be found during a static inspection.
Suitable for detecting performance problems.

Cons:

Setting up the reviewer’s system to run the code might be cumbersome and time-intensive.
Might distract the reviewer from actually reviewing the source code.
The review is limited to the scenarios the reviewer traces.

Academic Code Reading Techniques

Code review techniques described in academic papers aim at making code reviews more systematic. Those approaches detail exactly where a reviewer should look, the order of inspection, and also which questions to ask and issues to look for.

I summarize the approaches into two types (abstract-driven and functionality-driven) and only highlight aspects that help us to better design our own code reading and reviewing approaches.

9. Abstract-Driven Code Reviews

During abstract-driven code reading, the code reviewers read small pieces of code, and write down their understanding of the code (aka create descriptions or specifications). Then, the reviewers compare the description they created with the existing specification or documentation of the code. If there was a mismatch, they found a problem. To determine the order in which methods or functions are reviewed, academic approaches often use dependency information. Commonly, the reviewers are instructed to start with the methods that have the least dependencies on the other parts of the systems. This is in line with the bottom-up code review style.

10. Functionality or Use-Case-Driven Code Reviews

Another distinct set of reading techniques does not focus so much on the entities of the system (as described before), but rather on concrete use cases or functionality of the system. Here the aim is to check whether the code behaves correctly. For that, the reviewer first has to define use cases, and then inspect if the code implements the use cases correctly. This includes designing the preconditions for the use case, the success and failure conditions, and the exceptions. This approach reminds us of systematic testing approaches, whereby here the focus is on statically inspecting the code using control-flow and data-flow reading techniques, and not on the dynamic execution of the codebase.

Want to learn more about the presented code review techniques and see them in action? Have a look at my member-only articles on code review techniques here, or sign up for a free remote learning session.

This article first appeared on https://awesomecodereviews.com. Last updated: May 02, 2024

{
  "by": "sea-gold",
  "descendants": 0,
  "id": 40248247,
  "score": 3,
  "time": 1714747342,
  "title": "Best Code Review Techniques",
  "type": "story",
  "url": "https://www.awesomecodereviews.com/code-reading/code-review-techniques/"
}

{
  "author": null,
  "date": null,
  "description": "Learn about different code review techniques.",
  "image": "https://awesomecodereviews.com/static/1d74ad8de2c649f750ee9ec0bab4bff6/cbf46/code-review-technqiues-social.jpg",
  "logo": null,
  "publisher": "Logo Awesome Code Reviews",
  "title": "10 Best Code Review Techniques",
  "url": "https://www.awesomecodereview.com/code-reading/code-review-techniques/"
}

{
  "url": "https://www.awesomecodereview.com/code-reading/code-review-techniques/",
  "title": "10 Best Code Review Techniques",
  "description": "Systematically reviewing source code is an essential part of ensuring code quality and correctness of the code. Yet, most developers review their code ad hoc, which means they do not have any formal, or even...",
  "links": [
    "https://www.awesomecodereview.com/code-reading/code-review-techniques/",
    "https://www.awesomecodereviews.com/code-reading/code-review-techniques/"
  ],
  "image": "https://awesomecodereviews.com/static/1d74ad8de2c649f750ee9ec0bab4bff6/cbf46/code-review-technqiues-social.jpg",
  "content": "<article><section><p>Systematically reviewing source code is an essential part of ensuring code quality and correctness of\nthe code. Yet, most developers review their code <em>ad hoc</em>, which means they do not have any formal, or\neven explicit code review approach that they can easily describe. While a few formal code review\ntechniques exist, they are not widely known.\nIn this article, I show you different code review techniques you can use to make your code review\napproach more systematic, explicit, and effective. Those techniques are either dedicated code review techniques, or techniques from other development disciples, such as code reading, testing, or debugging,\nthat I adapted to facilitate the task of code reviewing to help you find more bugs, and understand the\ncode under review better.</p>\n<h2>Modern code review is ad-hoc</h2>\n<p>Most programmers review code in an <em>ad hoc</em> manner. This means there is no explicit, formal, or systematic process\nthat the team agreed upon to review code. Instead, the developers intuitively review source code files based on their experience.</p>\n<p>Which files, methods and even statements developers look at, and in which order, is up to the individual developer,\nand often even up to their current mood.\nSimilarly, which aspect or issues they look for in code is not well defined, and can change from developer to developer.</p>\n<h2>Junior developers struggle without concrete review techniques</h2>\n<p>While programmers develop their individual techniques for code reviewing over time,\nthose techniques are implicit, vary from person to person, and\noften only live in the developers’ heads.\nJunior developers therefore often wonder how exactly they should review code, and what to look for.\nThey learn how to review code by copying and mimicking what they see their peers do in code review.\nHowever, this process to learn code reviews is neither efficient nor effective.\nIt also means that each team member will have a slightly (or vastly) different approach to review code.</p>\n<h2>Transforming implicit to explicit knowledge</h2>\n<p>One of the best code review hacks a team can embrace is to transform the implicit knowledge that\nexperienced developers on their team have (basically in their head), into explicit knowledge.</p>\n<p>During such a transformation process, the experienced developer describes in detail what they do during a code review.\nOver time, those explicit guides to reviewing code, can become one overall guideline that describes how code is\nreviewed within a team.\nSuch a guideline serves two purposes: First, it streamlines how a team reviews code, and\nsecond, it allows people new to the team to learn quickly what is important during code reviewing.</p>\n<h2>Formal, systematic, and explicit review techniques</h2>\n<p>In addition to learning from the experience of senior developers, we can also learn from formal, systematic, and explicitly\ndescribed techniques for code inspection, code review and code reading.</p>\n<p>In this blog post, I show you some of the code review techniques I also teach\nin my <a target=\"_blank\" href=\"https://www.michaelagreiler.com/workshops/\">code review workshops</a>.\nThis can help you to transform your implicit and <em>ad hoc</em> reviewing techniques into\nexplicit and more systematic approaches.</p>\n<h2>Systematic Code Review Approaches</h2>\n<p>We will look at the following systematic code review approaches:</p>\n<ol>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#checklist\">Checklist-based Code Reviews</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#test-driven\">Test-Driven Code Reviews</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#bottom-up-top-down\">Bottom-up versus Top-Down Code Reading</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#control-flow-data-flow\">Control-flow versus Data-flow Code Reviews</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#pattern\">Pattern Recognition</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#referencing\">Cross-Referencing</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#change-impact\">Change-Impact Analysis</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#trace\">Trace-Based Code Reading</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#abstract\">Abstract-Driven Code Reviews</a></li>\n    <li><a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#functionality\">Functionality or Use-Case-Driven Code Reviews</a></li>\n</ol> \n<br />\n<h2 id=\"checklist\">1. Checklist-based Code Reviews</h2>\n<p>One of my favorite code review techniques involves using a checklist.\nThey are by far the most widely used <em>systematic</em> code review technique because the approach is\nstraightforward to implement and does not involve a lot of additional effort.\nIn empirical research, checklist-based code reviews have also been shown as very effective.</p>\n<p>Checklist-based code reviews involve using a predefined list of items or criteria to assess the code.\nA checklist can focus on a variety of factors such as coding standards, design principles,\nsecurity guidelines, and performance considerations.\nYou can find a <a target=\"_blank\" href=\"https://www.awesomecodereview.com/checklists/code-review-checklist/\">code review checklist</a> that covers\na wide range of topics here.\nSometimes, only one of those factors, for example, security, is the focus of such a checklist.\nThis makes sense when you want to perform a more thorough review in this specific area.\nHave a look at this <a target=\"_blank\" href=\"https://www.awesomecodereview.com/checklists/secure-code-review-checklist/\">security-focused code review checklist</a>\nas an example.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Provides a systematic and structured method for reviewing code, ensuring consistency and thoroughness.</li>\n<li>Helps reviewers focus on important aspects that might be overlooked otherwise.</li>\n<li>Assists in educating new team members about coding standards and best practices.</li>\n<li>Functions as a memory aid, ensuring important aspects are checked.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Correct usage of the checklist might be unclear or confusing.</li>\n<li>Aspects not covered by the list might be overlooked.</li>\n<li>May lack flexibility, as not all checklist items are applicable to every piece of code.</li>\n<li>It might be not clear where to look, as no order for inspection was given.</li>\n</ul>\n<p>Learn more about <a target=\"_blank\" href=\"https://www.awesomecodereview.com/checklists/code-review-checklist/\">checklist-based reading here</a>.</p>\n<h2 id=\"test-driven\">2. Test-Driven Code Reviews</h2>\n<p>During test-driven code reviews, the code reviewer starts by reviewing the test code before they\nreview the production code. The rationale behind this approach is to use the test cases as use cases that explain the code.\nThus, the code reviewer learns about the production code when they look at the test code, which helps\nthem create a mental model.\nThe tests are used as a specification of what the software is supposed to do, and the code reviewer\nlearns about the assumption the code author had about the code\nthrough the tests.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Helps improve the test code quality and thus maintainability and quality of the code.</li>\n<li>Ensures high test coverage and quality.</li>\n<li>Encourages writing meaningful tests that truly validate the code.</li>\n<li>Tests can help the developer understand the production code.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Depends heavily on the quality of the tests themselves.</li>\n<li>Can’t be done in the absence of tests.</li>\n<li>Tests might replicate the misunderstandings of the code author about the code’s specification.</li>\n</ul>\n<p>Learn more about <a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/test-driven-code-review/\">test-driven code reviewing here.</a></p>\n<h2 id=\"bottom-up-top-down\">3. Bottom-up and Top-Down Code Reading</h2>\n<p>All code reading techniques can be broadly categorized also into bottom-up or top-down reading.\nMost of the time, we use a combination of those two approaches. So, let’s have a more detailed look!</p>\n<h3 id=\"bottom\">Bottom-up Code Reading</h3>\n<p>Bottom-up reading means that the developer starts reading, understanding, and reviewing small fragments of the code first.\nBased on those small fragments, like single code statements, or small methods the developer works their way up to understand and evaluate\nmore and more of the functionality and quality of the software under review.\nThis way, the developer gradually builds a picture of how code elements interact to form the larger system.</p>\n<p>Bottom-up code reviewing works well when reviewing a small, self-contained piece of code, like a function or a class.\nOn the other hand, it also works well, when you have to review a larger piece of software you are\ncompletely unfamiliar with that lacks documentation.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Developers build a thorough understanding of the nitty-gritty details of the code.</li>\n<li>Helps to effectively identify <em>local</em> issues, bugs, and inefficiencies.</li>\n<li>The developer needs less overall context about the system, making it suitable for new team members or for reviewing isolated components.</li>\n<li>Works well for unclear or unfamiliar legacy code, or code that isn’t documented.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>It is a time-consuming approach due to the focus on details.</li>\n<li>Reviewers might miss the big picture, as well as architectural or higher-level design problems.</li>\n<li>When confronted with a large code change, starting at the lowest level can be overwhelming and inefficient.</li>\n</ul>\n<h3 id=\"top-down\">Top-down Reading</h3>\n<p>In a top-down reading approach, the software developer starts by reading, for example,\na user story or the documentation of the software first. These often non-code artifacts\nalready explain the purpose of the code under review and give the reviewer an overview of what to expect.\nThen, the reviewer examines the overall structure and components of the systems.\nThe goal is to build a mental model of the system before looking at the code in more detail.\nIn a later step, the reviewer tries to find the most significant method(s),\nthat drive the functionality and starts reviewing in more detail from there.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>This approach helps build an understanding of the system’s architecture and high-level design.</li>\n<li>It is effective in spotting problems with the overall design, structure, and integration points.</li>\n<li>The approach is suited for larger code changes or even complete codebases.</li>\n<li>It helps prioritize which parts of the code to focus on for a more detailed review.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Reviewers using only a top-down approach might overlook specific low-level coding issues or bugs.</li>\n<li>Requires the reviewers to have a good understanding of the overall system, which might not be feasible for newcomers.</li>\n<li>By examining only high-level artifacts, the reviewer might make incorrect assumptions about how high-level designs are implemented at the lower levels.</li>\n</ul>\n<p>Learn more about <a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/top-down-code-review/\">top-down code reviews</a> here.</p>\n<h3>Combining bottom-up and top-down code reviewing</h3>\n<p>In practice, a combination of both approaches is often used.\nStarting with a top-down review helps understand the system’s architecture and major components,\nsetting the stage for a more detailed, bottom-up review of specific areas of interest or concern.\nThis combined approach ensures the architectural integrity and the detailed correctness of the code.</p>\n<h2 id=\"control-flow-data-flow\">4. Control-flow and Data-flow Code Reviews</h2>\n<p>Two other complementary code review approaches are control-flow and data-flow code reading.\nControl-flow reading follows the execution of the program, whereby during data-flow reading you follow the data.</p>\n<h3 id=\"control-flow\">Control-flow Code Reviews</h3>\n<p>Control-flow reading focuses on understanding how the <em>program’s execution</em> progresses.\nIt examines the order in which statements, instructions, or function calls are executed\nand how the program moves from one part to another.\nThis includes looking at loops, conditional statements, function calls, and recursion.\nControl-flow driven code reviews are great for finding logical errors.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Highly effective in spotting logical problems with the flow of execution, such as loops, conditionals, and sequence of operations.</li>\n<li>Essential for understanding the execution order and for debugging issues like infinite loops or unexpected branches in logic.</li>\n<li>Helps in understanding the overall structure of the program, particularly the execution order and the interrelation of various components.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Reviewers might miss issues related to data handling or data integrity.</li>\n<li>It is less effective for data-intensive applications.</li>\n<li>Complex to perform in event-driven systems due to the non-linear progression of execution.</li>\n</ul>\n<h3 id=\"data-flow\">Data-Flow Code Reviewing</h3>\n<p>Data-flow reading focuses on how <em>data</em> moves through the program.\nThis includes tracking the source, use, and modification of variables and data structures,\nunderstanding how data is passed between functions, and examining how data state changes over time.\nData-flow code reviewing is particularly useful when looking at the code with a security lens.\nIt helps identify data leaks or points where sensitive data might be compromised.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Effective in identifying problems related to data handling, such as data corruption, improper use of data structures, and issues with data lifecycle.</li>\n<li>Particularly useful for uncovering security flaws that stem from the misuse of data, like buffer overflows or injection attacks.</li>\n<li>Helps in tracing how data moves through the system, which is crucial for understanding complex interactions and dependencies.</li>\n<li>Can identify inefficiencies in how data is processed, leading to opportunities for performance optimization.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Tracing data flow can be challenging, especially in large codebases with numerous data paths and interactions.</li>\n<li>Requires a detailed and thorough examination of how data is handled, manipulated, and transformed, which can be time-intensive.</li>\n<li>Focusing primarily on data flow can lead to overlooking issues related to control flow, such as logic errors or incorrect program sequencing.</li>\n</ul>\n<h3>Combining control-flow and data-flow code reviewing</h3>\n<p>In practice, both control-flow and data-flow reading modes are often used together during code review.\nUnderstanding how data is handled (data-flow) is crucial for evaluating the logic and sequence of operations (control-flow).\nFor example, in a function with complex logic, you might use control-flow reading to understand the sequence of operations\nwhile simultaneously using data-flow reading to see how data is manipulated throughout those operations.\nThis integrated approach provides a comprehensive understanding of the code, helping to identify both logical\nerrors and data-related issues.</p>\n<h2>Code Reading, Debugging and Program Understanding techniques</h2>\n<p>While reviewing code, we can make use of general code reading, debugging and program comprehension techniques.\nIn the following, I’ll briefly highlight some of the most useful techniques.</p>\n<h3 id=\"pattern\">5. Pattern Recognition</h3>\n<p>During pattern recognition, the code reviewer uses mostly a <a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#top-down\">top-down approach</a> to identify common patterns in the code.\nSuch patterns include design patterns, algorithmic patterns, or idiomatic expressions in the programming language.\nPattern recognition during code reviewing is helpful to create a mental model of the software system, but also\nto identify problems with the software’s architecture, or the design of algorithms.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Helps create a mental model of the code change and the structure of the code.</li>\n<li>Streamlines the review process and leads to more consistent review approaches even amongst different team members.</li>\n<li>Well suited to find problems within the software architecture or design.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Due to the focus on patterns, reviewers might overlook other problems.</li>\n<li>Using known and common patterns to judge code, can bias the reviewers and they might dismiss good, new approaches, just because they are not established yet.</li>\n<li>Reviewers need a broad knowledge of patterns and anti-patterns to look for.</li>\n</ul>\n<h3 id=\"referencing\">6. Cross-Referencing</h3>\n<p>During cross-referencing, the code reviewer systematically reviews the dependencies and relationships between code\nelements, such as classes, functions or variables. This approach is suitable to understand the interdependencies and also the\nimpact change can have on the system.\nAs manual cross-referencing is a tedious task, code reviewers can use tools to extract, display or visualize this information.\nMost IDE’s provide built-in tools that help with cross-referencing, which is also often used during code refactoring.\nThese tools build an index of all code elements and link them, which helps during navigation.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Finds dependencies, and relationships and reveals how a change impacts the rest of the system.</li>\n<li>Allows the reviewer to build a deep understanding of the codebase, and the code change under review.</li>\n<li>Reviewers get a good understanding of the control flow and the data flow, thus allowing them to identify errors in execution <em>and</em> data manipulation.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>If done manually, cross-referencing is tedious and error-prone.</li>\n<li>For larger code changes and systems might be overwhelming for the reviewer.</li>\n<li>Focusing too much on relationships and dependencies between artifacts can lead to overlooking other issues.</li>\n</ul>\n<h3 id=\"change-impact\">7. Change-Impact Analysis</h3>\n<p>During change-impact analysis, the reviewer gathers information to be able to\njudge how the code change will impact the rest of the system.</p>\n<p>While cross-referencing can be used as part of a change-impact analysis, a change-impact analysis is broader and also involves\nanalyzing more high-level artifacts, such as specifications, documentations to understand the impact of the code change.\nA reviewer will normally start by understanding the rationale behind the code change, and its description (<a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#top-down\">top-down</a>).\nThen, the reviewer will identify affected components, analyze the dependency graph and assess the impact of this\nchange on the functionality of the overall system. During such an analysis the reviewer should also\nlook at the impact on the test system: does it need tests to change, or the be added?</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Discussions on the impact of code changes can improve the understanding a team has of the overall codebase.</li>\n<li>Allows to direct reviewing efforts towards impacted and high-risk parts of the codebase.</li>\n<li>Reduces the risk of introducing bugs or regressions.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Change impact analysis can be very time-consuming.</li>\n<li>The reviewer has to have already a good and deep understanding of the codebase to understand the impact.</li>\n<li>It can lead to analysis paralysis, because the reviewer cannot completely envision all potential</li>\n</ul>\n<p>impacts of this code change, and is thus reluctant to approve it.</p>\n<h3 id=\"trace\">8. Trace-Based Code Reading</h3>\n<p>Trace-based reading, often used during debugging, involves following the execution of code at runtime. The code reviewer can do this\nby stepping through the code in a debugger or by examining logs or output traces.</p>\n<p>Most code reviewers use a static control-flow approach to review code, instead of this dynamic code analysis technique, that\nfocuses on understanding how the code behaves at runtime.</p>\n<p>This dynamic evaluation is useful when the code reviewer is puzzled by a certain part of the program,\nor expects a bug. It allows us to understand the state of the program at various points of execution,\nto track the sequence of function calls, and to observe changes in variable states over time.</p>\n<p><strong>Pros:</strong></p>\n<ul>\n<li>Allows the review to see how the system behaves at runtime.</li>\n<li>Effective during diagnosing or evaluating “potential” bugs and problems.</li>\n<li>Helps build a mental model of the code, thus helpful if the reviewer is unfamiliar with the system.</li>\n<li>Can help catch side effects or anomalies that cannot be found during a static inspection.</li>\n<li>Suitable for detecting performance problems.</li>\n</ul>\n<p><strong>Cons:</strong></p>\n<ul>\n<li>Setting up the reviewer’s system to run the code might be cumbersome and time-intensive.</li>\n<li>Might distract the reviewer from actually reviewing the source code.</li>\n<li>The review is limited to the scenarios the reviewer traces.</li>\n</ul>\n<h2>Academic Code Reading Techniques</h2>\n<p>Code review techniques described in academic papers aim at making code reviews more systematic.\nThose approaches detail exactly where a reviewer should look, the order of\ninspection, and also which questions to ask and issues to look for.</p>\n<p>I summarize the approaches into two types (abstract-driven and functionality-driven) and\nonly highlight aspects that help us to better design our own code reading and reviewing approaches.</p>\n<h3 id=\"abstract\">9. Abstract-Driven Code Reviews</h3>\n<p>During abstract-driven code reading, the code reviewers read small pieces of code, and write down their understanding of the\ncode (aka create descriptions or specifications).\nThen, the reviewers compare the description they created with the existing specification\nor documentation of the code. If there was a mismatch, they found a problem. To determine the order in which methods or functions are\nreviewed, academic approaches often use dependency information. Commonly, the reviewers are instructed to start with the\nmethods that have the least dependencies on the other parts of the systems. This is in line with the <a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#bottom\">bottom-up code review style</a>.</p>\n<h3 id=\"functionality\">10. Functionality or Use-Case-Driven Code Reviews</h3>\n<p>Another distinct set of reading techniques does not focus so much on the entities of the system (as described before),\nbut rather on concrete use cases or functionality of the system.\nHere the aim is to check whether the code <em>behaves</em> correctly.\nFor that, the reviewer first has to define use cases, and then inspect if the code implements the use cases correctly.\nThis includes designing the preconditions for the use case, the success and failure conditions,\nand the exceptions.\nThis approach reminds us of systematic testing approaches, whereby here the focus is on statically inspecting the code using\n<a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#control-flow\">control-flow</a> and <a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/code-review-techniques/#data-flow\">data-flow reading techniques</a>, and not on the dynamic execution of the codebase.</p>\n<p>Want to learn more about the presented code review techniques and see them in action?\nHave a look at my member-only articles on <a target=\"_blank\" href=\"https://www.awesomecodereview.com/code-reading/test-driven-code-review/\">code review techniques here</a>, or sign up for a free\nremote learning session.</p></section><p><i>This article first appeared on <a target=\"_blank\" href=\"https://awesomecodereviews.com/code-reading/code-review-techniques/\">https://awesomecodereviews.com</a>. Last updated: May 02, 2024</i></p></article>",
  "author": "mgreiler",
  "favicon": "https://www.awesomecodereview.com/favicon-32x32.png?v=7fe9b96b72b491c20782650014341995",
  "source": "awesomecodereview.com",
  "published": "",
  "ttr": 627,
  "type": "website"
}