Introduction

The need for rapid delivery, increased competitive pressure, and ever-changing requirements all increase the importance of quality control processes in the development lifecycle. Testing takes time, but time is of course not a commodity you have a lot of. One way to save time and improve the quality of your software applications is to introduce more testing as early as possible. An effective way of achieving this is through automated code reviews.

This article introduces a new feature of the IBM® Rational® Application Developer (IRAD) and IBM® Rational® Software Architect (RSA) products, one that allows you to automatically validate Java" code against a pre-defined set of rules and best practices. Code Review is designed to help you detect many well-known causes of problems in Java and Java" 2 Platform, Enterprise Edition (J2EE" Platform) applications.

Note: The RSA product includes all of the capabilities of the IRAD product, with additional features to support:

• UML 2 modeling
• Model-driven development
• Structural analysis
• Architectural control

The topics discussed in this article are relevant to both IRAD and RSA, but we will refer only to IRAD for the sake of brevity.

Intended audience

This article is intended for software developers and testers who are interested in using Code Review in their software projects. The article assumes a basic knowledge of Java and Eclipse user interface concepts (for example, Eclipse workbench or Eclipse perspective).

Conventions

This article will talk about the practice of code reviews in the generic sense, and will use upper-case (Code Review) when referring to the automated software quality tool that is part of IRAD. Text enclosed in square brackets (for instance, [Code Review Help]) denotes an entry in the Resources section at the end of this article.

Further information

This paper provides an introduction to Code Review and some of the Java and J2EE best practices that Code Review examines.Additional resources related to Code Review, Java, J2EE, and the IBM Software Development Platform can be found in the Resources section at the end of this article.

Additionally, there is extensive documentation on how to use Code Review -- as well as a reference of Code Review rules -- with the Code Review documentation that is included with IRAD and RSA. See the [Code Review Help] entry in the Resources section to locate this information.

Back to top

How Code Review fits into the IBM Software Development Platform

IBM Rational Application Developer for WebSphere Software, version 6, is the newest version of the IBM Rational IDE (integrated development environment) for Java and J2EE applications. It includes a wide range of developer tools that accelerate your ability to create industrial strength Java and J2EE applications. Previously, this product was known as IBM®WebSphere® Studio Application Developer.

IRAD is one of four new products that are part of the IBM Software Development Platform.

Other new members include:

• IBM® Rational® Software Modeler is a UML-based visual modeling and design tool for documenting and communicating different views of a system.
• IBM® Rational® Web Developer for WebSphere Software (formerly IBM® WebSphere® Studio Site Developer) is an integrated development environment that simplifies and accelerates your ability to develop, test, and deploy Web applications, Web services (including Web services that participate in Service-Oriented Architecture), or Java applications.
• IBM Rational Software Architect is a design and construction tool that leverages model-driven development with UML to help you create well-architected applications and services.

These three new products, together with IRAD, share a great deal of components and are based on the Eclipse framework.

Overview of automated software quality

Traditionally, software quality has been the main focus of a group of test specialists who evaluate functionality, performance, and reliability of software applications prior to their shipping to the customer. Typically, testers execute:

• Automated and manual functional testing
• Performance and load testing
• Test management and planning

These activities often cannot be performed in parallel to writing code, so they are completed after the code base reaches a certain level of functionality. Only at that point can testing experts start validating the functionality of the application.

Developer testing is part of the new effort focused on detecting and fixing problems during software development. Developer testing extends the idea of automated software quality into the Developer space.

Detecting problems in the development phase of a project significantly reduces the cost of fixing defects, increases the quality of produced code, and helps the team deliver the application on time. By making the effort to set up automated code reviews -- creating unit and component tests, as well as detecting memory and performance bottlenecks, in parallel to writing code --- returns in form of higher quality code and reduced development time.

Two of the four tools that make up the IBM Rational Software Developer Platform -- IRAD and RSA -- feature the following advanced developer testing capabilities:

• Code Review: static code analysis tool
• Component Test: extension of unit testing framework targeting J2EE components and web services
• Runtime Analysis: tools for analysis and debugging of important runtime parameters of an application (performance, memory usage, multithreading, and so on)

These developer testing tools enable you (whether you're a software developer or architect) to increase your productivity. In addition, they help you detect problems and prevent them from happening even before your QA team performs functional integration testing, or -- more importantly -- before a bug is introduced in the customer's production environment.

Overview of Code Review (static analysis)

Code Review is a feature of IRAD and RSA that validates the compliance of your code against a set of coding rules. The coding rules are organized into rule categories. Together, the rules and the categories build a rule set that can be configured in the Code Review Properties page. Every time Code Review detects a violation of a rule, it reports a new finding to you. All findings are sorted and presented in the Code Review Main view, and each of them is explained in the Code Review Details view.

In this first release, Code Review is shipped with approximately 220 rules grouped in the following categories:

• Design Principles: contains rules for design principles of object-oriented (OO) programming
• Globalization: contains rules that are based on globalization coding best practices, helping to ensure that code runs correctly in localized environments
• J2EE Best Practices: contains rules based on the best J2EE development practices, and supports web projects targeted to WebSphere servers
• J2SE Best Practices: contains rules that validate code for compliance with Java" 2 Platform, Standard Edition (J2SE") best practices for Java development
• Naming: contains rules regarding naming conventions for elements in Java code
• Performance: contains rules that enforce suggestions for improving performance and reducing memory footprint in Java applications
• Usage of Private APIs: contains rules that locate APIs that do not belong in Java code
• Structural Analysis (RSA only): contains a set of rules that helps you conduct an architectural review of your code

The rule categories are further organized into reviews. The selected review dictates which rules will be applied against your code.

Code Review is shipped with the following reviews:

• Quick Code Review: all the rules of the highest-severity problems
• Complete Code Review: all the rules
• J2EE Best Practices: all the rules from the J2EE Best Practices category
• Globalization Code Review: all the rules from the Globalization category
• J2SE Best Practices: all the rules from the J2SE Best Practices category
• Structural Analysis Code Review (RSA only): all the rules from the Structural Analysis category

From the Code Review main view, you can work with individual findings. Here is the list of activities that you can perform with findings:

• View details
• Open the source code location of the finding
• Apply a quick fix on an individual finding, or all findings of the same rule at once!
• Ignore (remove from the view)
• Sort findings per rule category, or per source files of their origin
• Filter findings based on their severity or their state (for instance, ignored or resolved)
• Search for a finding based on a search string, or a regular expression

The goal of Code Review is to help your development team standardize its coding style, and to ensure that you implement best coding practices. It works together with the compiler to ensure that the code base meets a certain level of quality. By integrating automated Code Review into your development environment, your team can detect and fix a number of bugs during development -- before these bugs transform into functional problems later in the development cycle, or in production.

Back to top

Setting up the sample project

Throughout this article, we use sample code that is available for download (CodeReviewDemo.zip). The sample code is a set of classes that illustrate the breadth of the problems that Code Review can automatically detect and fix.This section of the article explains how to run Code Review on a sample project. You may also choose to run it against your own code, since the usage model and the steps are likely to be similar to those described later in this article.

To set up the sample project, first create a new empty Java project, and then import the sample source files from the CodeReviewDemo.zip file.

Back to top

Using Code Review

Code Review is part of the base installation of IRAD and RSA. The main view of Code Review is integrated into Java perspective, but it is not opened by default. You can run Code Review either from the navigator or from the Code Review main view. To open the Code Review main view, click Window > Show View > Code Review in Java perspective, as shown in Figure 2.

Out of the box, Code Review will run the basic Quick Code Review against the whole Workspace. To start this review, click the Play button in the Code Review main view.

Note: If you are in a perspective other than the Java perspective, Code Review may not be accessible from the Show View menu. In this case you, can access Code Review using the following steps:

1. Ensure that Java Development capability is enabled by clicking Window > Preferences, then Workbench > Capabilities, and ensuring that Java > Java Development is selected. Click OK.
2. From the application menu, click Window > Show View > Other.
3. Expand Java, select Code Review, and click OK.

Code Review views

The Code Review tool consists of these four views:

• Main
• Details
• Preferences page
• Rule editor

The Code Review main view is used to start the analysis, and to manipulate and review the findings. Figure 3 illustrates that when it is opened for the first time the view is empty, and only the main controls are enabled. After a review is finished, this view contains the list of categorized findings and basic statistics about the run.

The Code Review Details view is opened automatically when you double-click one of the findings. The purpose of Code Review Details is to provide a description of the finding, examples, and suggestion(s) for the fix, as shown in Figure 4.

The third view is the Code Review Preferences page. The Preferences page can be opened by clicking the Manage Rules button in the Code Review main view, or by launching the Preferences dialog and navigating to Java > Code Review.

In the Code Review Preferences page, you can select the code review you want to apply the next time you run the tool. You can also configure the rules and their properties. When you select a code review at the top of the page, only the rules that belong to this review will be displayed.

Please note that Quick Code review is the default review, and it only includes all the rules of the severity problem. Warnings and recommendations are not part of this review. To see all of the available rules (Figure 5), select Complete Code Review.

Finally, the Rule editor enables you to extend the rule set with additional rules. Figure 6 illustrates how the editor provides a set of templates that guide you through the definition of the new rule, making the process easy and straightforward. A new rule is created through the instantiation of a template. RSA has all of the templates available in IRAD, and an additional set of templates for the creation of Architectural Control rules.

Run Code Review

In general, running the Quick Code Review consists of the three simple steps:

1. Open Code Review
2. Run the analysis
3. Review results and fix problems

In this example, we will review the entire workspace using the pre-defined Quick Code Review. Because this is the default configuration, to run the analysis, you can simply click the Play button on the Code Review toolbar. A progress indicator in the lower right-hand corner of the screen will indicate percent complete. Depending on the size of the workspace and the number of enabled rules, the duration of the review may vary. The review runs in the background and displays results as it finds them.

Once a review begins, you can stop it at any time by pressing the Stop button, which appears instead of the Play button (on the Code Review toolbar) once the Code Review is started. If you stop a Code Review run early, all of the findings detected before you stopped it will remain for your analysis.

You will know your analysis has completed when the progress indicator reaches 100% and disappears. Additionally, there will be a Finished code review message in the lower left-hand corner of the workbench.

The review results in a set of findings, which we will examine in the next section.

Review and fix

Once you have run the analysis, you can improve your code based on the Code Review findings

Review findings

Code Review findings are displayed in the body of the Code Review main view, as shown in Figure 7. They are grouped by category and annotated with a priority. Since we applied the Quick Code Review, only the findings of the severity problem were detected.

If you are using the sample code, go to the Code Review main view, and expand the J2SE Best Practices: Nullcategory. You will see one finding titled NullEmptyArray_Example: 21 Avoid returning null instead of empty array. This finding is composed of the:

• File name (NullEmptyArray_Example.java)
• Line number (21)
• Title of the rule that the code violated (Avoid returning null instead of empty array)

Double-click the finding. The Code Review Details view will open and display additional information about the problem that was discovered. This action has two results (see Figure 8, following):

• The source file (NullEmptyArray_Example.java) is displayed in the IRAD editor
• The Code Review Details view is opened in your IRAD workbench

The Code Review Details view describes the rationale and mechanics behind the particular rule that your code has violated. The Details are divided into three parts:

• Description explains why the finding is a potential problem, and provides a link to the instance of the violation of the best practice in your code
• Example provides a sample of incorrect code
• Solution shows the same code, changed to fix the problem

Fixing the code

You may fix a result either by manually editing the offending source code or by using a pre-defined Quick Fix, if one is available. If a Quick Fix is available, the icon next to the finding will have a light bulb next to it. There are two different finding icons (illustrated in Figure 9): the one with the light bulb indicates that a Quick Fix is available, while the one without a light bulb requires a manual fix.

The example we've chosen (NullEmptyArray_Example.java) includes a Quick Fix. Right-click the Finding in the Code Review view and click Quick Fix: Return zero-length array. You will then see a pop-up window showing the code before and after the Quick Fix is applied, as shown in Figure 10. Click OK and Code Review will automatically fix the offending code.

Code Review will mark the item as fixed by changing the finding icon to a checkbox. You may also undo the Quick Fix by right-clicking the fixed finding and clicking Undo Quick Fix. Note that if you manually fix a result item, you must re-run Code Review to verify that it doesn't report a problem any more.

Ignoring a result

You may deem a particular result not applicable to your team, or to the context of the result within your program, and explicitly deciding to ignore it. To ignore a result, right-click the finding and click Ignore Match. You can then hide the result by clearing Ignored in the Filters dialog box.

Back to top

Further steps

The steps described above show you the basic ways to use Code Review on an individual project. Code Review has an additional set of features that can help with standardizing the automated code reviews in a team of developers. Such an advanced usage model requires the following steps for optimal results:

• Use Complete Code Review instead of Quick Code Review -- as discussed previously, the Quick Code Review deals only with the most important findings detected during the review. To improve the quality of code further (for example, increasing performance, correctness, and maintainability), use Complete Code Review, which provides additional rules of the severity warning and recommendation.
• It is highly recommended to review and configure all the rules prior to the selection of Complete Code Review. This will help you fully understand the findings and their correct prioritization.
• Here are some suggestions for your configuration of the Complete Code Review:

• Select Complete Code Review in the Code Review Preferences page
• Review each rule in the rule base and decide whether to use it or not.Once this decision is made, you should apply the rule consistently in all of your projects.
• Exclude packages and classes that are not your responsibility. This will reduce the number of reported findings and help you focus on problems in the relevant code only.
• Review the severity of each of the rules and change it if needed.
• Use the built-in rule editor to create additional rules.
• Define a single Complete Code Review configuration for your project (or your development team), and share it using the Import/Export capability. The user-defined rules, their selection in the configuration, and the custom rule properties and their prioritization can all be exported into a zip file and imported into another IRAD or RSA development environment. Rule sharing can help you create project-specific rules and rule configurations. This will allow you to collect code quality metrics, and implement the same best practices across the development team, thus further improving the maintainability of your code.

Back to top

Summary

Code Review is a powerful new tool for enforcement of best development practices, with the purpose of improving the code quality during code implementation -- the phase in the development lifecycle when detecting and fixing problems is the least expensive.

This article introduced Code Review, which detects violations of Java and J2EE best practices. It discussed where the tool fits into the overall IBM Software Development Platform, explained how to use it, and described some advanced techniques that experienced users can employ to improve their productivity.

It is important to remember that Code Review is a robust and customizable tool. We recommend that you explore the Code Review Help inside of IRAD and RSA to learn even more about its capabilities. Also, we are very interested in hearing what you think about Code Review and this article, so please feel free to contact the authors if you have a question or comment.

Resources

Learn

• J. Bloch, Effective Java Programming Language Guide, Addison-Wesley Publishing Co., Reading, MA (2001).This book provides detailed information on many best and worst practices of Java programming language. It describes in detail many of the rules that are included in the J2SE Best Practices category.
  
  
• R. Johnson and D. Reimer, Issues in the Development of Transactional Web Applications , IBM Systems Journal 43, No. 2, 430-440 (2004). This paper, co-written by the lead developer of the SABER application that preceded Code Review, discusses some of the underlying problems that are present in transactional systems like J2EE.
  
  
• The IBM Software Developer Platform homepage provides detailed information on the overall IBM Software Development platform, of which IRAD, RSA, Automated Software Quality, and Code Review are a part.
  
  
• [Code Review Help]. Be sure to peruse the Help pages within Rational Application Developer. This is the documentation that ships with the product. The Code Review documentation can be found under Developing application code > Detecting and analyzing runtime problems > Reviewing code automatically. These pages provide a wealth of information.
  
  

Get products and technologies

• For technical resources about Rational's products, visit the developerWorks Rational content area. You'll find technical documentation, how-to articles, education, downloads, product information, and more. For specific information about Rational Application Developer, visit the RAD technical resources page.
  
  
• Get the evaluation version of Rational Application Developer from the Trials and betas page.
  
  
• Rational's software development process, Rational Unified Process version 2003.06.13, is also available from the Trials and betas page. See the Continuously Verify Quality documentation for information about the "why's" of Automated Software Quality.
  
  
• Purchase Rational books at discounted prices in the Rational section of the Developer Bookstore.
  
  

Discuss

• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Ask questions about Rational Application Developer and Rational Software Architect in the Rational Software Architect, Software Modeler, Application Developer and Web Developer forum.
  
  

About the authors

Goran Begic joined Rational Software in the Netherlands in 1999. Since then, he has worked in technical support, field enablement, product management, and sales for the IBM Rational PurifyPlus family of developer testing tools. He also has expertise in implementing agile development practices. In 1996, he earned a bachelor's of science in electrical engineering from the University of Zagreb.

Bill Higgins, an architect with IBM Global Services, works on collaborative development technologies with IBM's On Demand Workplace and Rational organizations. Currently, he is researching portal-based solutions to assist software development teams. His technical interests include the IBM® Rational Team Unifying Platform,® IBM Lotus Workplace,® IBM WebSphere Portal Server,® mapping business processes to IT, and recording his activities and insights in his IBM developerWorks blog. He holds a BS in computer science from Penn State University.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• How Code Review fits into the IBM Software Development Platform
• Setting up the sample project
• Using Code Review
• Further steps
• Summary
• Resources
• About the authors
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into Rational on developerWorks

Rational offerings on the IBM Cloud

Quickly scale develop & test environments

Special offers