Phase 1: Configuration
Tools and processes are all well and good, but in practice, someone has to get the ball rolling. That person is the review initiator. Many people can play this role. It could be the owner of the code, the team leader or project manager, the chief architect, or even a QA person. It's up to you to decide what suits your organization best.
Keep in mind that many developers will consider code reviews a bit of a choreat best, and they will not come forth and volunteer their code for a code review. Others will delay the process as long as possible, waiting for their code to be as perfect as possible (for example, after the delivery date when they have more time), or just hoping that people will forget about them. If this is the case, then the team leader or architect should take responsibility for initiating code reviews.
A couple of other considerations may also weigh in favor of a centralized approach:
- Initiating a review involves assigning team members as reviewers.
- Initiating a review involves deciding which types of issues will be evaluated.
Although the special DEFAULT review entry can define default values for these fields, many organizations will prefer to have these activities done centrally by one person (e.g., the project manager, the architect, or the lead developer).
On the other hand, for some projects, it may be more appropriate to have individual developers commit their own code. The advantages of this approach include the following:
- When you notify reviewers that some code is ready to be reviewed, you should include a brief description of the purpose of the code (for new code) or the justification for the change (for changes to existing code). This is often best done by the developer.
- For any non-trivial classes, unit tests and unit test results should be submitted for review at the same time as the classes. Again, the developer is probably the best person to do this.
This approach works well if a single person is responsible for committing code to the next release version candidate. In open source projects, this person is often called the committer. In this sort of project organization, developers may commit their code to configuration management whenever necessary, but the committer is responsible for committing reviewed code to the release candidate code (which is often a new branch in the configuration management system). This also gives developers a good reason to have their code reviewed: if it isn't reviewed, it won't make it into the release version!
In any case, whatever strategy you adopt, it is important to agree on who initiates code reviews and who participates. You need to put this down in writing and to make sure everyone knows and understands the process.
To initiate a review, open the project properties and go to the Review entry. Click on New... to create a new review entry (see Figure 2). Each review entry corresponds to a real physical code review. You need to specify an identifier (unique to this project) and a short description. The identifier becomes the name of the .jupiter file, so remember to put something compatible with a file name structure.
Now, specify the source code files you want to review (see Figure 3). Typically, a code review will concentrate on one class, though it may include some other related or dependent classes as well.
|Figure 3. Specifying the Source Code Files to Be Reviewed|
The following screens enable you to select the review team (see Figure 4) and the code author. Jupiter stores the comments of each team member in a separate file under configuration management, so you should use filename-compatible names (such as logins) for your team members. To make life easier, you should put the whole team into the DEFAULT review item; new reviews will then display this list by default.
In the following screens, you can specify issue types, severities, and so on. You usually leave these screens as-is: any modification of these lists should be done in the special DEFAULT review.
Next, you have to define a place in your source code directories where the review XML files will be stored. This is a directory relative to your project root directory.
Finally, you can set up filters for different situations (see Figure 5). Each phase has its own filter, which you can customize to let people concentrate better on the work to be done during that phase.
The filter feature is best illustrated by discussing the default filter for each review phase, which works quite well:
- Individual Phase: The default filter for this phase is
'Reviewer:automatic', which means that individual reviewers will see only their own review issues.
- Team Phase: The default filter for this phase is
'Resolution:unset', which simply means that during the team review, reviewers will see all the issues that have not been resolved. In Jupiter-speak, the 'resolution' of an issue is when the review team decides on which action to take, either "Valid needs fixing" (the issue is a real issue, which needs to be fixed) or "Invalid won't fix" (the issue is not a valid issue, so no corrective action will be taken).
- Rework Phase: The default filters for this phase are
'Assigned to:automatic' and
'Status:open'. When the reviewers decide on an action, the task is assigned to a team member (usually the author). These filters display only the issues that have been assigned to the current user and that are still open.
All of the fields described here take their default values from the special DEFAULT review item. So it is worthwhile to set up the DEFAULT review item with sensible project-wide values.
Once the review is set up, commit the .jupiter files to configuration management. Now you need to let all the reviewers know about it. A simple and efficient way to do this is to use a mailing list or a shared IMAP mailbox. You should define a suitable standard template for review notifications in your organization and project. A review notification format might include the following information:
- A standard subject field, including the project name, the designated reviewers, and possibly a component name
- A description of the code to be reviewed: what does it do, what does it fix, and so on (You may want to refer to requirements documents such as use cases.)
- A change log
- New and deleted files, if any
- Any affected components not included in the review
- Unit test classes and unit test results
Once everyone is notified, the actual review process can begin.