What's New in v5.0?

How to Use CodeCollaborator

CodeCollaborator is a web-based tool that simplifies and expedites peer code reviews, maximizing software developer time, fostering team communication, and ensuring that reviews are happening and bugs are being fixed. Its flexible interfaces and workflows allow CodeCollaborator to be implemented in diverse environments.

Although many workflows are possible, let's look at the out-of-the-box configuration.

Planning Phase

Uploading files for review
(Click to enlarge)

The review begins in the "Planning" phase when you, the author, upload files for review and invite the other participants.

You can upload files that have not yet been checked in to version control (i.e. review before check-in), or files that have already been checked in (to review after check-in or to review a set of branch changes). SCM integration makes the upload of changed files typically a one-click or one-command process. However, any set of files can be uploaded, whether under version control or not.

Reviews can have multiple participants, including one or more reviewers and zero or more observers in addition to the author. Reviewers are responsible for careful review, and subsequent review activity depends on their consensus; observers are invited and can participate but their consensus is not required.

The "Planning" phase is complete when you finish uploading all necessary files and inviting the desired reviewers and observers. The review then enters the "Inspection" phase.

Inspection Phase

Side-by-side file diffs
(Click to enlarge)

When the review switches to "Inspection," CodeCollaborator notifies all participants to alert them that the review is starting.

CodeCollaborator presents reviewers with the uploaded files, with a highlighted view of before/after code differences (if the files were under version control).

You have several options available for the difference view's appearance, including the choice of side-by-side or above-below diff viewer, the ability to ignore whitespace, a preference to skip unchanged lines, and whether or not to word-wrap long lines of code. Code Collaborator displays many common source code files with syntax-highlighting.

Commenting on an individual line of code
(Click to enlarge)

Anyone can begin a conversation by clicking on a line of code and typing, and you can have any number of conversations going on at once. The associated line of code and an overall review summary display keep the conversation threads distinct.

Comments can work either like instant message chat or like newsgroups. If everyone is chatting at the same time, you have a real-time "instant message" environment so the review can progress swiftly. If one or more participants are separated by many timezones or aren't currently at the computer, the chat looks like a newsgroup where you post comments and receive notifications when someone responds. CodeCollaborator works equally well no matter where your developers or reviewers are located.

Opening a defect
(Click to enlarge)

Reviewers open a "defect" for every change you (the author) need to address before the review can be deemed complete. Like comments, defects are associated with files and lines of code and show up in the threaded conversations (both chat- and newsgroup-style) on the code alongside the comments. You can also create a defect for the review as a whole.

The "Inspection" phase is complete when all reviewers indicate it's ready to move to the next phase. If defects have been opened, the review proceeds to the "Rework" phase; otherwise the review moves to the "Complete" phase.

Rework Phase

Defect log and per-file summary
(Click to enlarge)

In the "Rework" phase, you (the author) are responsible for fixing the defects found in the "Inspection" phase.

This change might be as simple as correcting a typo in a comment, or as complex as a complete rework of the task involving different files than in the original review.

When you believe all defects are fixed, you upload the fixed files to the server and prompt the review to re-enter the "Inspection" phase so reviewers can verify the fixes and ensure no new defects have been introduced in the process.

Complete Phase

When the review is complete, that's it!

If you (as the author) have uploaded some version control changes that weren't yet checked in, CodeCollaborator sends you a notification reminding you that the changes may now be committed.

Metrics

Although metrics are vital for process measurement and improvement, developers have better things to do than spend time collecting them. CodeCollaborator computes the following metrics completely automatically:

• Inspection Rate: Thousands of lines of code inspected (kLOC) / Man-hour
• Defect Rate: Defects found / Man-hour
• Defect Density: Defects / kLOC

Because you can break out defect data by severity and/or type, you can also correlate defect rates from code review with the rates from QA to determine relative efficiency and phase-containment.

While rates vary widely, Code Collaborator users typically find one defect about every 10-15 minutes.

For more information about how to interpret these metrics and what other case studies have shown about them, get a free copy of our book on peer code review.

Administrative Control

The system administrator can control the process in several ways.

He can define custom data fields so that review participants must provide information specific to their organizations. He can set up different review templates to handle different types of reviews; each review template can specify its own set of custom data fields. A review template can also define its own roles (e.g. Moderator, Author, Reviewer, Observer, Reader, and Tester). Each role has a distinct set of permissions, help-text, and requirements during a review.

The system administrator can specify a variety of access controls, including whether non-participants can see review materials, whether users are allowed to cancel or delete a review, and whether a version control system's access control list should be enforced.

In some cases, it is desirable to require code reviews before code can be checked into version control. To accommodate this workflow, CodeCollaborator has several built-in tools that can be installed on the version control server to enforce this rule to varying levels of strictness.