Are you using a toolset in your code review?

To conduct software reviews and inspections smoothly, you need a set of tools that includes techniques for reading phases, roles, and software tools. Most people think review and inspection must be manual, with little room for tools and automation. However, there are software tools to make reviews and inspections more efficient, structured, and at least semi-automated. This article introduces a toolset for code reviews that includes the techniques and software tools that you need.

Shuji Morisaki (smrs@is.aist-nara.ac.jp), Graduate School of Information Science, Nara Institute of Science and Technology

Shuji Morisaki received a doctorate in information science from Nara Institute of Science and Technology, Japan. He joined an Internet service provider and engaged in the planning, development, and management of online services as a product manager. He is conducting research on software review/inspection, software measurement, and empirical software engineering. He is involved in the Working Group of International Research Cooperation on Software Inspections as Japan representative.



23 February 2010

Also available in

Introduction

Many people imagine code review as programmers poring over source code. To be effective, that kind of code review requires the participation of super programmers and technical experts. No doubt, having such experts detect defects seems thoughtful and effective. However, in practice, it is incredibly difficult to get adequate time from such experts just to have them find and detect defects.

This does not mean that the entire software review and inspection activity depends from beginning to end on having state-of-the-art experts do the work. In fact, many sub-activities to be automated can be accomplished without special skills using software or other convenient sets of tools, including static analysis software, role assignment, and checklists.

Many articles report the effectiveness of using a toolset (see Resources). This article presents a toolset for code reviews, along with examples of how these tools are used. However, many of these tools can be used in review and inspection of other artifacts, such as requirement specifications and design documents. This article concludes with a short discussion of how using tools can improve reviews and inspections, and ongoing work in this area.


The code review process

Table 1 shows the phases and activities involved in software review and inspection, as defined by Fagan (see Resources). The author added the "Toolset" section. The rest of this article introduces items in the toolset with these phases.

Table 1. Phases of software review and inspection
OverviewPreparationInspection (defect detection)Rework (correction)Follow-up
Task content
  • Decide roles
  • Decide viewpoint and techniques
  • Schedule
  • Determine review/inspection targets
  • Understand target in line with role
  • Assign roles
  • Uncover defects per assigned role
Defect correction
  • Verify corrections
  • Verify that secondary defects have not been introduced
Toolset
  • Role definition
  • Reading techniques
  • Static analysis tool
  • Role assignment
  • Coding conventions
  • Compiler (Warnings)
  • Reading techniques
  • Static analysis tool
  • Role assignment
  • Reading techniques
  • Review tool
  • Defect tracking tool
  • Review tool
  • Defect tracking tool
  • Review tool
  • Defect tracking tool

Overview, preparation, and inspection/defect detection phases

Role definition and assignment are another tool for review and inspection

When roles are unclear during review and inspection, smooth progress is difficult. Roles are assigned in the inspection phase, and participants of review and inspection identify issues during this phase according to their roles. In that sense, the role definitions themselves serve as a tool during review and inspection. Table 2 is based on IEEE 1028, "Standard for Software Reviews and Audits" (see Resources), and the research paper "An Encompassing Lifecycle Centric Survey of Software Inspection" (see Resources). An individual may play multiple roles, or more than one individual may play the same role. For example, two or more individuals may play the role of reviewer/inspector.

Table 2. Roles for software review and inspection
RoleDescription
ModeratorThe moderator is responsible for leading participants toward objectives. Usually, a single person acts as moderator and works to prepare an environment in which defects can be readily detected within a specified time to keep things moving. The moderator keeps the discussion from wandering and ensures that discussion does not outpace the ability of the recorder to record detected defects. Time management is also an important role of the moderator.
Reviewer/inspectorReviewers/inspectors try to identify and detect defects. Usually, all members can be assumed to be reviewers/inspectors regardless of their specific roles.
RecorderThe recorder is responsible for capturing the content of all defects detected by the reviewers/inspectors. Usually, a single person acts as recorder. It requires experience to accurately and fully capture these detected defects. When they are gathered via mail, the recorder is responsible for eliminating duplicates and summarizing defects detected.
OrganizerThe organizer is responsible for putting together the plan, including the overall development plan, and determines the timing of review/inspection.
Author The author has developed the product to be reviewed or inspected. The author is responsible for the correction of defects.
Reader/presenterThe reader explains the product under review/inspection. A reader should be someone other than the author and explains the product on behalf of the author.

Overview, preparation, and inspection/defect-detection phases

Reading techniques

Reading techniques can ease the process of identifying code defects. The most common reading technique is the use of a checklist. The list includes questions such as "Have resources been properly freed?" and "Will performance suffer from excessively nested loops?" This list is designed to help reviewers detect defects. Using such checklists, reviewers read through the source code, looking for areas related to these questions. The questions in checklists may be tailored or selected to suit the target software.

Perspective-based reading is a reading technique that gives each reader a specific viewpoint to use, such as "user" or "tester." Reports indicate that this technique is effective in comprehensively uncovering defects because the review is conducted from multiple perspectives. A person assigned to the user perspective is expected to read through the code with use cases in mind. A person assigned to the tester perspective will read through the code thinking about what test cases could prove that the code works properly.

In this way, perspective-based reading creates a broader perspective for detecting defects than with ad-hoc review. The perspective of the readers does not necessarily need to match their actual role in the project. The user perspective, for example, may be assigned to the project leader. In addition, a perspective may be broken into detailed perspectives. Table 2 shows the perspectives for each programmer skill involved in the project (see Resources for more information.)

Table 3. Example perspectives for perspective-based reading, introduced on an IEEE Software article by Denger and Shull (see Resources)
Novice developerExpert developer
IntroductionUse the use cases to focus your review.Read from the most complex and important part. Also consider which sets of classes should be understood by developers who must understand the whole system functionality.
InstructionPrioritize the use cases by importance. For each use case, try to trace the flow of control through the code that would be called.Prioritize your review by importance and complexity.
Questions
  • Are there enough comments in the source code?
  • Is there error handling at each user interaction?
  • Is error and debug logging enough for localizing bugs?
  • Are the data structures used appropriately, taking into consideration trade-offs between performance and memory?
  • Is the code correct with respect to the use of floating-point numerics?
  • Would it be worth the extra effort to make it reusable and available to the team?

Preparation and inspection/defect detection phases

Identify areas for review and inspection with a source-code static analysis tool

The phrase "source-code static analysis tool" is a general term for a tool that extracts information from the source code itself without executing the program. Such analysis includes calculation of source-code metrics, detection of potential bugs based on defined patterns, and discovery of violations of coding conventions and rules. This analysis is beneficial for code reviews because it identifies locations in the code that are prone to bugs. For example, methods, functions, a class, or a module of complex logic might be identified. Many studies have reported that bugs are easily introduced into such complex areas. Identifying such areas allows code review efforts to be focused on such critical regions, raising efficiency.

Static analysis tools also can help to find resource leaks, such as failures to deallocate memory or release resources, by identifying potential source code.

Source-code metrics may include many things, including the number of branches and loops, the number of function or method arguments, the number of function or method calls, and the number of lines of source code. Many case studies have shown that the defects are more easily introduced into complex areas, such as those with many branches or loops. It has been shown that such metrics are related to quality. You can't find bugs in source code simply by measuring source-code metrics, but you can locate source code that has a high probability of containing a bug. Source code that has a high probability of containing bugs is called "fault-prone code." There are many research papers that analyze open source projects. You can also see this relationship in the downloadable metrics from the Metrics Data Program NASA IV&V FACILITY (see Resources).

There are also some tools that will detect areas in source code that are likely to access null pointers or addresses beyond array boundaries. These tools estimate the execution flow from the source code. The following developerWorks articles (see Resources) introduce such source-code static analysis tools:

  • "Rational® Software Analyzer"
  • "Static analysis IBM® Rational Software Analyzer: Getting started"

Finally, at the frontier of the state-of-the-art, there are static analysis tools capable of extracting design patterns from source code. Identifying the location and type of the design pattern helps the reviewer understand the source code. It can also help find potential defects peculiar to a specific design pattern. Links to these tools can be found in Resources:

  • Design Pattern Recognition tool
  • DPR
  • DP-Miner

Source-code static analysis tools allow you to gain a better sense of where to focus review efforts, allowing you to decide what parts to review during the preparation phase, and efficiently discover potential bug areas during the inspection phase.


Preparation phase

Coding conventions, rules, and guidelines reduce code review effort

Coding conventions, also coding guidelines or coding rules, are a set of guidelines that define programming practices. A programming language has its own language specifications. The compiler and runtime interpreter follow the language specification. Coding conventions, by contrast, aim to prevent defects and make the code easier to read. Code that does not comply with the language specifications cannot be executed, while code that fails to comply with coding conventions may still run.

The aim of coding conventions can be many and varied, but typically, conventions are established to improve readability, extensibility, and reliability of the code. Conventions aimed at readability includes such things as the use of line breaks, treatment of whitespace like tabs and spaces, and the formatting of conditional statements. Conventions aimed at extensibility involve things like using defined constants instead of explicit numbers. This allows changing the value of a constant to change all instances of it throughout the code at once. Conventions aimed at reliability involve things such as refraining from using recursive functions or goto statements that tend to make code complex and prone to bugs. goto statements and recursive function calls may be supported by the language definition, but it is known that using other methods makes the code easier to understand.

There are many coding conventions, including those for industrial applications, those used as a condition of delivery, publicly available conventions, and those used within an organization. The MISRA-C coding guideline for C language source code used in vehicle applications, and GCC coding conventions (see Resources) are examples of the many coding conventions, guidelines and rules in existence.


Preparation phase

Compiler warnings also help

Most compilers have the ability to issue warnings for statements that may cause bugs, even though these statements do not cause a compilation error. Compared to dedicated source-code static analysis tools, the functionality is usually limited, but worth trying. With the open source compiler GCC, detailed warnings can be generated by specifying the command-line option -Wall.

Such warnings are generated with the specific location (line number) within the source. For example, the warnings include locations where variables are declared, but not used within any functions or methods, locations where variables are used without initialization, and locations that attempt to use unrecommended libraries. Correcting the source code to remove warnings can decrease the possibility of introducing bugs and improve readability.


Inspection/defect detection, rework/correction, and follow-up phases

Review tools and defect-tracking tools

Software tools designed to support code reviews have features for browsing the source code, making annotations at any location within the code, and listing the annotations. Figures 1 and 2 show screenshots of Jupiter, a collaborative code review plug-in for Eclipse. In Figure 1, line 29 has an annotation of "The accessibility modifier which should be private is public," and the Review Editor tab at the bottom of the screen shows the entry state. In the lower portion of Figure 2, the Review Table pane captures all annotations in a table format.

In addition to Jupiter, there are many other review tools, including Review Board and Rietveld. Bug- and issue-tracking systems are also helpful for recording and tracking defects detected. If you’re using BTS or ITS for testing phases and a text file or spreadsheet application for recording defects in requirement design and coding phases, add "Identified during review" as a bug category and try these tools.

Figure 1. Recording issues in the Jupiter code review plug-in
Screenshot shows Jupiter in Eclipse with a code annotation
Figure 2. Table of defects detected in the Jupiter plug-in (bottom pane)
Screenshot shows Jupiter's analysis of problems in code within an Eclipse environment

Toward more sophisticated reviews and inspections

Using a toolset to prepare the code for the eyes of others before a review or inspection shows consideration for the reviewer/inspector. Without this, reviewers and inspectors can easily become aggravated, feeling "Why must I read this?" and begin identifying issues that are not essential or even attack the author personally. Good preparation can help prevent such situations.

As the scale or length of time involved in review and inspection increases, collaboration support and workflow-management software may become necessary. Such software can be useful in managing in a comprehensive way the results and state of progress of reviews and inspections.

Among the tools for code review introduced in this article, role definition, reading techniques, review tools, and issue-tracking tools are not limited to source-code review alone. They can also be used for the review and inspection of project plans, requirements definitions, specifications, design documents, test plans, operations manuals, and user manuals.

Reviews and inspections are an established practice for many organizations and open source development projects. High integrity, fundamental, and safety critical software demands review and inspection. However, compared to other software development activities, the review and inspection activity has less published information available. I hope that this article helps to promote developing and spreading information about reviews and inspections.

With the goals of establishing a community for review and inspection and publishing an analysis of code reviews by practitioners, the Working Group of International Research Cooperation on Software Inspections held Software Inspection Workshop 2009. Table 3 gives an overview of that workshop. The purpose of the workshop was for attendees to learn reading techniques and hear about research on inspections at Fraunhofer IESE and Nara Institute of Science and Technology.

Table 4 shows the program of the workshop and Figure 3 shows pictures of the workshop. Currently, Fraunhofer IESE, Germany and Nara Institute of Science and Technology, Japan are analyzing and discussing the results of the workshop for a possible research paper.

Table 4. Software Inspection Workshop 2009 overview
Date2 Jul 2009
PlaceCampus innovation center Tokyo (Tamachi, Tokyo)
HostingWorking Group of International Research Cooperation on Software Inspections
Co-hostingNara Institute of Science and Technology, Japan
Fraunhofer IESE, Germany
IBM Japan
Table 5. Software Inspection Workshop 2009 program
Opening
Kyoko Hattori (IBM Japan)
Introduction on the workshop and software inspection
Shuji Morisaki (Nara Institute of Science and Technology, Japan), Frank Elberzhager, Marek Jawurek (Fraunhofer IESE, Germany)
Quality assurance and defect prevention by independent verification and validation
Hironobu Hosokawa (IBM Japan)
Explanation of inspection materials
Frank Elberzhager, Marek Jawurek (Fraunhofer IESE, Germany), Shuji Morisaki (Nara Institute of Science and Technology, Japan)
Inspection and discussions among attendees
Introduction of Rational Software Analyzer
Koshimizu Yoshiyuki, Atsuhi Kurokawa (IBM Japan)
Panel discussion
Moderator: Jun-ichi Niino (Publickey, Japan)
Paneler: Hironobu Hosokawa, Yoshiyuki Koshimizu and Shuji Morisaki
Closing
Figure 3. Pictures of inspection and discussion by attendees
Pictures of inspection and discussion by attendees

Acknowledgments

In writing this article, I received invaluable assistance and cooperation from the attendees of the workshop, Kyoko Hattori, Koh'ichi Miyagawa, Frank Elberzhager, Marek Jawurek, Jun-ichi Niino, Nobuhiro Hosokawa, Yoshiyuki Koshimizu, Atsuhi Kurokawa, Michael D. Barker, Yuichiro Yasuda, Kyohei Fushida, and Yasutaka Kamei. Some of the research introduced in this article was conducted under the program "The Development of Next Generation IT Infrastructure." This work is being conducted as a part of StagE Project, the Development of Next Generation IT Infrastructure, supported by Ministry of Education, Culture, Sports, Science and Technology, Japan (MEXT). Additionally, some of the research introduced in this paper received Grants-in-Aid for Scientific Research (B), No. 21700033) from MEXT.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=468809
ArticleTitle=Are you using a toolset in your code review?
publish-date=02232010