Rational Team Concert Code Review
This article introduces Rational Team Concert (RTC) code review, which was first released in version 6.0.1. It highlights the capabilities of the tool, how to configure it for your projects, and how to leverage other capabilities built into RTC to ensure that you have an effective code review process that is streamlined and efficient for your development team.
Code inspections can yield more bugs on average than testing, more bugs are found per hour when compared with various testing methodologies, and it’s inexpensive. Code review is ranked among the top three methodologies for finding bugs with only high volume beta testing and modeling or prototyping being ranked higher. Code review averages about twice the yield of traditional test methodologies such as unit, function, system, and integration testing.
There are other benefits of code reviews aside from finding defects. The practice leads to better compliance to coding standards, improved clarity, and better documentation. When you have multiple people reviewing code it tends to promote code reuse, gives team members exposure to different areas of the code, and improves overall team coding skills.
Some teams conduct informal lightweight reviews such as pair programming, over the shoulder reviews, or simple email exchanges between peers. On other teams, code reviews can be highly formalized systematic reviews. In regulated industries with very low tolerance to defects, deep and exhaustive reviews is essential. Consider avionics and automotive industries where defects in mission critical code can result in serious injury or death. Recently, an Advanced Driver Assistance System (ADAS) failed to detect and react appropriately to a crash scenario that cost the life of the driver.
How do software development teams ensure that effective and efficient code reviews are conducted for their projects? Some considerations when selecting a code review tool and methodology include whether teams are co-located or dispersed geographically, the degree of formality in their review process, the need for traceability and auditability, the ability to manage review findings, and developer preferences.
The next three sections provide an overview of the features of RTC code review, introduces RTC concepts and terminology for readers who are not familiar with RTC, and provides an overview of the components of the code review tool. Next there are instructions for project administrators on enabling code review for their projects and some optional process advisors (aka preconditions) to help you ensure compliance to your review process. Finally, there is a description of the code review work flow – how to start a review, manage issues and code changes during the review, and complete a review.
Code review features
Code review is integrated with RTC work items and Jazz SCM to provide developers with a seamless, low overhead work flow that is simple to use and is a natural extension to their daily activities. There isn’t a separate server installation, additional licensing fees or other costs associated with using RTC code review. Enabling code review for your projects is simple and takes only a few minutes to set up.
Reviewers can annotate specific lines of code, which helps developers quickly see and fix issues. Issues (or findings) can be marked as must-fix and the reviewer can accept or reject the changes. When preconditions are enabled, a code review cannot be approved if must-fix issues have not been resolved to everyone’s satisfaction.
Developers don’t have to worry about the intricacies of issue management because this is handled for them. Each issue has its own discussion thread and events are logged as the review progresses. Whenever an issue is updated, a new issue raised, or new code changes are added to the review, the events are logged so that you have a complete history of the review life-cycle. Because code reviews are iterative and can include code changes during the review cycle, any annotations on lines of code (issue markers) are automatically re-positioned and visual cues are provided to the reviewer so that they can easily see what has changed since they last looked at the code or since they last reviewed issues.
Team collaboration is accelerated through real-time notification of pending reviews, issues, and fixes. This is becoming more and more important as the number of globally distributed development teams increase. In fact, with the RTC SCM development team spread across three different time zones, it is common for them to have code changes that were written in one time zone reviewed by team members in another time zone.
Code review enables auditing for compliance. Issue status at delivery, approval information, the event logs, and other information captured during the review can be used for a variety of metrics and reporting requirements.
Since the introduction of code review in 6.0.1 more features have been added. Reviewers can inspect intermediate before and after file states which is useful in advanced SCM workflows encountered when multiple developers are working on a common code base.
The ability to extract work items is useful when an issue needs to be addressed but shouldn’t prevent delivery of the current code changes. The extracted work item captures the required work and will have its own code review cycle.
A new command is available to export code review data such as issues raised, issue activity, reviewer information, code delivery status, and other metrics in JSON or XML format. This enables customers to use their existing reporting tools or custom scripts for auditability and other reporting requirements.
Concepts and terminology
This section is intended for users who are new to RTC. The concepts and terminology presented here can help with your understanding of the work flows that are described later on in this article. For more information about RTC see Rational Team Concert Knowledge Center.
The work item is the mechanism in RTC to track and coordinate development tasks and workflows. You can create your own custom work items but there are several that come out of the box when you install RTC. The common work items that developers typically work on are defects, tasks, and enhancements.
As the developer makes changes to files, he collects them up into a change set –a change set is an object that collects a related group of file or folder changes. The action of adding a change to a change set is called check-in. The developer can continue to make changes to the same or other files and check them into the change set. During this time the change set is active (or open).
After the developer has finished his code changes he completes (or closes) the change set. No more changes can be made or added to the change set. If he discovered that he needed to make more changes he adds the new changes to a new change set. So effectively, a work assignment can result in one or more change sets.
Next, the developer associates the change set(s) to the work item that was assigned to him. If code review has been enabled for his project, as described in Enable code review and enforce policies, the developer sees the code review presentation on the Approvals page of the work item. After the required approvals are in place, the developer can share the changes with team members by delivering the change sets to the team’s development stream. Other team members can accept the changes into their own workspace.
Code review components
Code review consists of three components: the RTC work item, a compare editor for reviewing code changes and annotating lines of code with issues, and an issue editor for describing and discussing issues.
Figure 1 shows the approvals page of a work item in the JUnit project which is a sample project that you can install out of the box. The new code review presentation displays under the approval section. It is recommended that you configure your project area, so that the code review section displays here, since you can see the review status and the approval states all in one view. However, the location of this section is entirely up to the project administrator.
In the code review section you can see the target stream where the changes will be delivered (JUnit in our example), the associated change sets, and a summary of issues. You can navigate to the files for a look at the currently open (unresolved) must-fix issues.
Figure 1 – Work item approvals page
If you click the Open Code Review the compare editor opens (shown in figure 2).
Figure 2 – Code review compare editor
You can use the compare editor to view before and after states of the source code. On the right is the before state, and on the left is the after state showing the file with the change sets applied. The before and after states are selected by default to be the initial file state and the final file state with all of the change sets applied respectively. However, you can use drop down menus to select intermediate file states to view what changed between two versions of the file.
To the far left is the navigator panel that is used to browse files and issues. Bold font is used to highlight files or issues that have not yet been viewed by the user since the file or issue was last updated.
When you click on a file it is opened in the compare editor, and clicking on an issue opens the issue editor as shown in figure 3.
Figure 3: Issue editor
Issues can be opened on a line of code or you can create general issues associated with the overall changes sets under review. For example, you can raise a general issue to remind the author to include a copyright statement in all files. In our example, an issue has been opened on line 1125. Clicking on an issue in the compare editor or navigator panel opens the issue editor. When the issue editor is open, the selected issue is highlighted in the compare editor as shown in our example. Also, an issue icon is positioned beside the line in the compare editor so that you can easily identify where in the code issues have been raised. Hovering over an icon displays the issue ID and summary and, in the event that multiple issues were raised on the same line of code, you see a list of issue IDs and summaries.
In the issue editor you can mark an issue as must-fix, which can be used to ensure resolution before approving a code review. More details on policies and, more specifically, preconditions are covered later in Enable code review and enforce policies.
When an issue has been addressed, the author marks it as resolved. This action triggers an event that sends an email notification to the reviewer. Note that all actions that change the state of the review, including the addition of change sets, new issues raised, comments, and must-fix/resolution state changes, are logged in the issue editor so you can view its activity history and enable reporting.
This was a quick overview of the components of code review. We will come back to the code review work flow later but before we do, you need to configure it for your project area. Detailed instructions are provided in the next section, Enable Code Review and enforce policies, and is intended for project administrators. If you or your project team will be conducting code reviews and are not interested in configuring it, you can go directly to Roles in the review process.
Enable code review and enforce policies
To configure code review for your project area, you will need to be a project administrator to add the code review presentation to the work item types that your team uses to contribute code to your project. Generally several work item types such as defects, tasks, and enhancements involve code changes and require approvals so we’d want code review to appear for all of them. Refer to the IBM Knowledge Center for instructions, A video demonstration shows how to enable code review for the JUnit project.
RTC has the ability to optionally enforce policies that we strongly recommend you enable for your project area. Specifically, you can specify conditions that must be satisfied before an SCM deliver operation can be executed. This is great for ensuring your organization’s policies are enforced before allowing code changes to get into production. There are two existing preconditions on the Deliver Operation (that is, when your changes are delivered from your repository workspace to a stream) that you will find useful: Require Work Items and Comments and Require Work Item Approval.
The precondition Require Work Items and Comments requires that change sets are associated with a work item. There are other constraints you can specify in this precondition, but it is necessary for RTC code review that the change sets to be reviewed are associated with a work item.
The precondition Require Work Item Approval prevents delivery of your change sets if the requirements for approval have not been met It specifies approval types, roles, and the number of approvals that are required in order to deliver a change set. This precondition is essential to the RTC code review work-flow and should be defined for your projects.
Two new preconditions have been added on the work item Save operation specifically for code review. The precondition Require Approver to Review all Files ensures that approvers have reviewed all files in the attached change sets before approving the work item. The precondition Requires Must-Fix Issues Resolved Before Approval restricts a reviewer from approving a work item if there are must-fix issues that are not resolved.
Let’s walk through an example, using the Eclipse client to configure the Require Work Item Approval precondition on the deliver operation.
Example: Setting the Require Work Item Approval precondition
In this example, set the precondition on the JUnit project.
- Open the JUnit project area from the context menu in the Team Artifacts
Figure 4: Open JUnit project
- In the Configuration column of the Project Area editor, expand Team Configuration and click Operational Behavior.
- In the Operational Behavior editor panel, scroll down to the source control operations. Because you add this behavior for everyone, select the Deliver (server) column entry for everyone, (the default).
- In the Preconditions panel, click the Add… button and in the Add Precondition dialog box, select Require Work Item Approval. Click OK.
Figure 5: Add precondition
- To specify the number of reviewers and their required rolls, in the Required Approvals section, click on the New… button.
- In the New Required Approval dialog box, select the type and required number of approvers. In this example, you specify that there is an approval of type Review and that two team members must approve. Click OK to add the required approvals.
Figure 6: New required approval
- Save the changes to your project area.
Roles in the review process
A code review involves two primary roles – an author and one or more reviewers. RTC work items and code review are loosely coupled but work items are integral to the code review process. The individual who is the owner of the work item is generally the person making the changes, adding the change sets to the work item, and ultimately delivering the changes to production. This person is considered the author.
Approvers of type ‘review’ on the work item are considered to be reviewers. Reviewers inspect the changes to look for potential defects and to ensure compliance with their team’s coding standards. But anyone with the appropriate permissions (project area/team area) can review the code and raise issues – this ability is not limited to approvers. Nonetheless reviewers are distinguished by the fact that they are ultimately responsible for approving or rejecting the code changes. They have a formal stake in ensuring code quality, compliance to standards, security, etc. of the software that makes its way into production.
Code reviews are iterative – there can be multiple coding-review-fix cycles during a code review before the changes are ready to be delivered to production. Change sets are typically added during the review cycle. Both reviewers and authors are notified whenever change sets are added, new issues are raised, and exiting issues are resolved or commented upon.
Let’s have a look at the key aspects of performing a code review – how to start a review, manage issues and changes, and complete a review. Note that the discussion assumes that you have configured all four process advisors described in Enable code review and enforce policies.
Starting the review
After the author has finished making code changes and has satisfied any other requirements that your organization has (for example, static analysis, unit testing, etc.) then the author is ready to submit the code for review. Before submitting code for review, the author must complete the following steps:
- One or more change sets are checked in and complete.
- The change sets are associated to a work item.
- An approval of type review is created and one or more approvers (reviewers) are assigned.
- The target stream where the code will be delivered has been specified.
Steps 1 to 3 are typically performed in the rich client; step 4 is performed in the web client. Because RTC is flexible and can be customized to your method of working, there is more than one way to meet the above requirements. The next section describes a recommended work flow.
Author submits changes for review
In this example you use the Eclipse client, where the rich client is needed to perform an action. Otherwise use the web client.
- In the Eclipse client the author creates one or more change sets.
- When the code changes are ready for review, in the Pending Changes View, right-click on the change sets; then, click Submit for Review….
Figure 7: Submit for review action
- In the Submit Changes for Review wizard, complete the following steps:
- On the Associate Work Item page, select an existing work item o create a new work item. Because a developer is assigned work through a work item, select an existing work item. Click Next.
- On the Submit for Review page, add a comment to the work item so reviewers know that you are not planning to add additional changes; then, reviewers can start their review. This is a good practice, especially when several review several cycles are involved. Also add approvers (reviewers). In this example, Markus and Jason are added as approvers. The subject is also named Code Review.
Figure 8: Submit for review page
- Click Finish to submit your changes.
Note: If you did not check-in your change sets, you are prompted to check them in now, in order to submit them for review. Also, your change sets will be completed for you if they weren’t already.
Note: It is good practice to suspend your change sets when you submit your code for review. This removes the change sets from your repository workspace but preserves it in the repository so that you can perform other work without creating dependencies. Once the review is complete, you resume the change sets and deliver your changes.
- Open the work item in the web client. You can see that your comment has been added on the Overview page; the change sets have been added to the Links page; and the new approval is displayed on the Approvals page, with Jason and Markus as approvers.
Figure 9: Approvals page
Also the code review section on the approvals page is populated. At this stage, it displays a checklist (introduced in release 6.0.2) to remind you of which items to complete in order to start the review. In this example, you select a stream, which is used for resolving file paths that are displayed in the code review UI. Note, the act of selecting a stream does not trigger delivery of the change sets to the stream.
- To select a stream, click Select Stream…. After you select a stream, all requirements for starting the review are met. The checklist is replaced with the code review summary, where you can view a summary of issues, a list of general must-fix issues, and must-fix issues on each file in the change sets (there aren’t any yet because the review hasn’t started).
Note: The button to open code review is visible, so you are set to go. Reviewers are notified by an email that they have been asked to perform a code review. The author can sit back and wait for notification that issues have been raised.
Figure 10: Code review section
Managing issues and changes
The author receives an email notification when a new issue is raised or an existing issue is modified (a comment is added or the must-fix designation is modified). The author can click on the issue link in the email to go directly to the code review and the specific issue. The author can add a comment indicating the action to take, discuss the issue further, or if there is a fix, the author can add the new change set(s) to the work item and resolve the issue. All of these actions result in notifications being sent to the reviewers. Also, all actions are recorded in an activity log in the issue editor.
Some issues can be resolved without a code change, as agreed between the author and reviewer. In other cases, the issue results in a code change. It is recommended that the review proceed in distinct approval cycles. For example, in this case Markus and Jason are asked to review the author’s change sets. Markus approved it, but Jason opens a must-fix issue and rejects the review. In this example, Jason rejects it because he reminds the author that a test for Modulus was also requested. The author adds the new test and submits his changes for review by using the same process described earlier in this article, but this time naming the review Code Review-2. In the Submit for Review wizard, the author again selects Markus and Jason as approvers and this time around both reviewers provide their approvals as shown in figure 11.
Figure 11: Approvals page for a second review
At this point, the required approvals are in and the author has the green light to deliver his changes to the production stream.
It is important to note that this is a recommended process because it clearly distinguishes review cycles and provides a “handshake” process between author and reviewers. Change sets are reviewed and either approved or rejected. A review cycle is rejected if additional changes are required of the author before he is permitted to deliver his changes. When new change sets are added, a new review cycle is instantiated with the cycle repeating until the code is finally approved for delivery.
Completing the Review
A code review is considered to be complete when the requirements for approval have been met. As discussed earlier, this is configurable for your project area by using process preconditions. Our example required two approvals from team members.
This example used preconditions on work item approval to ensure that due diligence is done by reviewers. You specified that approvers must review the latest code changes in all files. You also prevented a reviewer from approving the work item if there were unresolved must-fix issues. But there can be scenarios where an issue that is identified as a must-fix should not hold up the current code changes. You can work around this scenario by extracting issues into work items.
When an issue is considered to be important and must be addressed, but not necessarily as part of the current coding effort, it is best handled in a separate work item. In this case, the author (or reviewer) can extract one or more work items from the issue, so that this work can proceed independently and be subject to its own code review cycle. When extracting a work item the issue should be marked resolved – especially if you have the precondition Requires Must-Fix Issues Resolved Before Approval enabled for your project area.
Let’s take a look. Markus raised general must-fix issue 3 to add more advanced tests to the suite. The author clicked on the button (plus sign in the issue editor) to extract a work item, which brings up the New Work Item dialog box shown in figure 12, where he has specified that it is a task, filed against JUnit Tests, and is assigned to Jason. The description field is automatically populated with a link to the source issue.
Figure 12: New Work Item dialog box
Figure 13 shows the updated issue where we can see that work item 65 has been extracted. It’s a URL, so you can get to the work item from here. Note the activity log in figure 13.
Figure 13: Issue editor showing extracted work item
Conclusion
Rational Team Concert (RTC) code review was first released in version 6.0.1. It is integrated with RTC work items and Jazz SCM to provide developers with a seamless, low overhead work flow that is simple to use, effective and efficient. RTC code review supports formal or lightweight reviews, and enables effective collaboration regardless of whether teams are co-located or dispersed geographically. A simple user interface allows for easy annotation of lines of code, comparison of before and after files states, and issue management. Traceability and reporting support auditability and metrics to drive continuous improvement.
This article highlights some of the features of RTC code review. It explained the key components of the tool and how to quickly set it up for your projects. It shows how to start a review, manage issues and changes throughout the review cycle, and how to complete the review. For more details and video demonstrations, please refer to the references below.
Special thanks to David Lafreniere and Dejan Custic for their valuable contributions.
References
The Code review user guide is available on Jazz.net. You will need a user id and password which you can get at https://jazz.net.
Three part demo series on Code review based on version 6.0.1:
Part 1: Introduction to Code Review
Part 2: Configuring Code Review
Part 3: Performing a Code Review
Working with the code review tool on the IBM Knowledge Center.
Copyright © 2016 – IBM Corporation
Yes