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
|Overview||Preparation||Inspection (defect detection)||Rework (correction)||Follow-up|
|Task content||Defect correction|
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
|Moderator||The 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/inspector||Reviewers/inspectors try to identify and detect defects. Usually, all members can be assumed to be reviewers/inspectors regardless of their specific roles.|
|Recorder||The 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.|
|Organizer||The 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/presenter||The 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 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 developer||Expert developer|
|Introduction||Use 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.|
|Instruction||Prioritize 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.|
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
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.
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
goto statements that tend to make code complex and prone to
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.
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
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
Figure 2. Table of defects detected in the Jupiter plug-in (bottom pane)
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
|Date||2 Jul 2009|
|Place||Campus innovation center Tokyo (Tamachi, Tokyo)|
|Hosting||Working Group of International Research Cooperation on Software Inspections|
|Co-hosting||Nara Institute of Science and Technology, Japan|
Fraunhofer IESE, Germany
Table 5. Software Inspection Workshop 2009 program
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)
Moderator: Jun-ichi Niino (Publickey, Japan)
Paneler: Hironobu Hosokawa, Yoshiyuki Koshimizu and Shuji Morisaki
Figure 3. Pictures of inspection and discussion by attendees
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.
- Learn more about the relationship between quality and metrics in "Developing Interpretable Models with Optimized set Reduction for Identifying High-Risk Software Components," published in IEEE Transactions on Software Engineering.
- Read more about skills required for code inspections in C. Denger's and F. Shull's article "A Practical Approach for Quality-Driven Inspections" from IEEE Software.
- See an existing standard in The Motor Industry Software Reliability Association's "Guidelines for the Use of the C Language in Vehicle Based Software."
- Read about the phases and activities involved in software review and inspection, as defined by M.E. Fagan in his article "Advances in Software Inspection (PDF)," published in IEEE Transaction on Software Engineering.
- See the GNU Coding Convention for another example of a coding standard.
- Check out the IEEE Std 1028-1997 IEEE Standard for Software.
- See more about how metrics can affect quality in "A Hybrid Faulty Module Prediction Using Association Rule Mining and Logistic Regression Analysis," published in Proceedings of the Second International Symposium on Empirical Software Engineering and Measurement.
- Read "An encompassing life cycle-centric survey of software inspection" from the Journal of Systems and Software.
- Learn more about the affectiveness of using toolkits in "Preliminary Results On Using Static Analysis Tools For Software Inspection," from proceedings of International Symposium on Software Reliability Engineering.
- Learn more about perspective-based reading of a requirements specification in the developerWorks article "Getting requirements right: The Perspective-Based Reading technique and the Rational Unified Process."
- See metrics about "fault-prone code" from the Metrics Data Program NASA IV&V FACILITY.
- Learn more about source-code static analysis from the developerWorks articles "Rational Software Analyzer" and "Static analysis IBM Rational Software Analyzer: Getting started."
- For pattern analysis in source code, check out the following tools: Design Pattern Recognition tool, Design Pattern Recovery (DPR), and DP-Miner.
- To listen to interesting interviews and discussions for software developers, check out developerWorks podcasts.
- Stay current with developerWorks' Technical events and webcasts.
- Follow developerWorks on Twitter.
- Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
- Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products, as well as our most popular articles and tutorials.
- The My developerWorks community is an example of a successful general community that covers a wide variety of topics.
- Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
Get products and technologies
- Innovate your next open source development project with IBM trial software, available for download or on DVD.
- Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
- Participate in developerWorks blogs and get involved in the developerWorks community.
Dig deeper into Open source on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Keep up with the best and latest technical info to help you tackle your development challenges.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.