Blog
Our team balked at code reviews at first. Now we can't imagine working without Code Collaborator.
How CodeCollaborator works
CodeCollaborator is a system for managing peer code reviews. Its flexible interfaces and workflows allow it to be implemented in diverse environments.
Although many workflows are possible, let's look at the out-of-the-box configuration.
Planning Phase
The review begins in the "Planning" phase where the author uploads files for review and invites the other participants.
Files are typically either not yet 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 plug-ins (provided by Smart Bear) make this typically a one-click or one-command process. However, any set of files can be uploaded, whether under version control or not.
There may be other participants, including one or more reviewers and zero or more observers. The former are responsible for careful review, and subsequent review activity will depend on their consensus; observers are invited and can participate but their consensus is never required.
The "Planning" phase is complete when the author decides the correct people are invited and all necessary files are uploaded. The review then enters the "Inspection" phase.
Inspection Phase
When the review switches to "Inspection," e-mails are sent to all participants to alert them the review is starting.
Reviewers are presented with the uploaded files with a side-by-side before/after highlighted difference view (if the files were under version control).
Several options are available for the difference view including: ignore whitespace, skip unchanged lines, and whether or not to word-wrap long lines of code. Many common source code files are displayed with syntax-coloring.
Anyone can begin a conversation by clicking on a line of code and typing. Any number of conversations can be going on at once; the associated line of code and an overall review summary display keep the conversations threads distinct.
Comments work a bit like instant message chat and a bit 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 just aren't currently at the computer, the chat looks like a newsgroup where you post comments and receive e-mails when someone responds. This means CodeCollaborator works equally well no matter where your developers or reviewers are located.
Reviewers open a "defect" for every change the developer will need to make before the review can be deemed complete. Like comments, defects are associated with files and lines of code and show up in the conversations (although you can also create a defect for the review as a whole).
The "Inspection" phase is complete when all reviewers say it's complete. If defects were opened, the review proceeds to the "Rework" phase; otherwise the review moves to the "Complete" phase.
Rework Phase
In the "Rework" phase the author is responsible for fixing the defects found in the "Inspection" phase.
This might be as simple as fixing a typo in a comment, or as complex as a complete rework of the task involving different files than in the original review.
When the author believes all defects are fixed, she uploads the fixed files to the server and causes the review to re-enter the "Inspection" phase so reviewers can verify the fixes and ensure no new defects have been opened in the process.
If the author (or any other participant) needs to ask a question or otherwise re-open the review, he can do that prior to uploading fixes. The review will also re-enter the "Inspection" phase.
Complete Phase
When the review is complete, that's it!
If the author had uploaded some version control changes that weren't yet checked in, the author is sent an e-mail reminding her that the changes may now be committed.
Metrics
Although metrics are vital for process measurement and improvement, developers don't want to spend time collecting them. CodeCollaborator computes the following metrics completely automatically:
- Man-hours / kLOC (Inspection Rate)
- Defects / Man-hour (Defect Rate)
- Defects / kLOC (Defect Density)
Because you can break out defect data by severity and/or type, you can also correlate defect rates from review with those from QA to determine relative efficiency and phase-containment.
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.
Different roles can be set up to handle different types of reviews (e.g. Moderator, Author, Reviewer, Observer, Reader, Tester). Each role has a distinct set of permissions, help-text, and requirements during the review.
In some cases it is desirable to require code reviews before code can be checked into version control. In this case, CodeCollaborator has several built-in tools that can be installed on the version control server to enforce this rule to varying levels of strictness.