Main page

The main page is what you generally see after logging in. By default, it lists all the review projects that have not been completed, although you can see all projects by selecting the 'Show/hide completed projects' menu item.

You can sort the project list by any of the columns by clicking on the column header. The first click sorts in the forward direction, the second reverse, and the list supports a two-level sort. Once you've found the project you want to review, click on the 'Review files' link to go to the Project page. This is also how you get to the Project page in later stages, e.g. to record that you've completed any required actions for a comment.

Project page

The project page shows all files selected for reviewing in the review project (they've been selected for you by the project owner).

The top of the page shows the project name and project state (e.g. 'Reviewing files'), as well as the tag or baseline names for the original file set (if any) and modified file set for the project. If the project owner has added project notes, a note icon will show next to the status, as will a toggle link labelled 'Show/hide notes' - clicking on either the icon or link will toggle display of the notes.

The next section of the page shows project comments, grouped by thread (or title). You can sort the comments by any of the columns. Clicking on the number of comments or the thread name opens the Comment dialog for the thread, while clicking on 'New thread' opens a Comment dialog to create a comment for a new thread. Hovering the mouse over the number of comments for a second will bring up the comments at the top-right corner of the window. You can hide all the project comments using the 'Show comments' toggle link.

Project comments are used to record issues that relate to the review project as a whole, to more than one file, or apply to more than one place in the codebase. They are commonly used for issues such as failing to follow your agreed code style.

Each file to be reviewed is listed, and colour-coded according to the file colour codes. The table shows the number of comments on the file, the file name and its path within the project, and any review priority set by the project owner for the file. It also shows some file statistics - the number of lines, the approximate percentage of the file changed, and the number of diff chunks (regions of the file with changes). You can sort by any of these columns.

If the project owner has added file notes to any file, a notes icon will show in the right-hand column. Clicking any icon (or the 'Show file notes' link in the column header) toggles display of the file notes.

The 'Reviewed?' column gives a rough indication of how likely it is that you have already reviewed the file (useful when your reviewing is spread over hours or days). A score of '0' indicates that you haven't even viewed the file, while a score of '5' indicates that you've probably reviewed all of the file. See file review scores for details of the scoring system. You can clear these scores using the 'Clear review tracker' link at the bottom of the page.

Clicking on the comments number (first column) for a file will open the Comment dialog for the first line in the file with comments. Clicking on the filename takes you to the File Review page. As for project comments, hovering the mouse over the number of comments for a second will bring up all comments for the file at the top-right corner of the window.

The page periodically polls the server for updates to the number of comments for each file, and for the project as a whole.

Tips:

• If your browser supports tabbed browsing (and if it doesn't, you should change right now), it's handy to leave the Project page open, and to open the files you're reviewing in separate tab pages.
• The sort orders you select for the project comments and project files is important, as this same order will be used on the project comments page, and on all next/previous links in the file review page and the comment dialogs
• The 'Show filename first' link allows you to toggle between showing each file path as '/path/to/file.ext' (the default), or 'file.ext (in /path/to)'.

File Review page

The file review page shows the code for one single file - this is the page where most of your time will be spent.

The top of the page shows the file name, directory, and any file notes added by the project owner (using the standard toggle icon and 'Show file notes' link so you can disable their display). There are also toggle links for showing or hiding lines of code that have been removed, and for viewing the diff as side-by-side or inline (or unified).

The 'Other information' link shows a pop-up menu for viewing the commit log in the Version Control System (if this is a Subversion project), and for viewing other reviews for this same file in other review projects. Each of these displays the on a new page. The choices for viewing other reviews are:

• Match file name only, i.e. find any file with the same name
• Match full path, i.e. find only files whose full path matches.

Below are link bars showing the locations of comments and diffs in the file. Each bar is made up of 20 regions, with each region acting as a link to that part of the file, and an indicator of the comments or diffs in that part of the file. Note that the links don't necessarily take you exactly to the comments or diffs you're after - you may have to scroll down after clicking the link, especially on larger files.

The remainder of the page shows the text of the file, using the file colour codes to indicate the changes that have been made. If using the side-by-side diff mode, the original version of the file is on the left, and the modified version on the right.

At the start of each line is a line number - clicking on this brings up the File comment dialog so that you can add a file comment against that line, or review other people's comments. If there's already a comment on the line, the number shows as white on red, and hovering the mouse over the link for a second will bring up the comment at the top-right corner of the window.

When using the side-by-side diff mode, the line numbers show the actual number of the line within each version of the file. However, when using the inline (unified) mode, the line numbers represent the line within this diff page, NOT the line number within the file. The difference is that deleted lines are counted (and shown) here, whereas of course they no longer appear in the real file.

If this is a Java source code file, you may (hopefully) find that class names show as links. Clicking on one of these links opens the class - if the class is part of the review set it'll open in another File Review page, otherwise it'll be a File View page. If there's more than one class with the same name, you'll be presented with a list to choose from. Note that this linking to class files is very basic - it's just a text search, so you'll find a few false positives.

The menu at the top of the file allows you to:

• Move to the next or previous review file in the project, based on the sort order you set on the project page. Note that hovering the mouse over one of these links shows the name of the file you'll navigate to, and position in the review list, and the total number of files in the list.
• Show all comments for this file - this brings up the File Comments page.

The following shortcut keys can be used:

• N (upper-case) - Move to next review file
• P (upper-case) - Move to previous review file
• n - Move to start of next diff chunk
• p - Move to start of previous diff chunk
• m - Move to next comment
• o - Move to previous comment
• > (shift + .) - Move to next line
• < (shift + ,) - Move to previous line
• s - Show any comments for the current line at the top-right corner of the window
• c - Show any comments for the current line in the comment dialog. NOTE: You will probably have to adjust the settings on your popup blocker to allow this.

File comment dialog

The file comment dialog is a pop-up relating to comments on a single line in a file being reviewed.

At the top is a few lines of context from the source code, using file colour codes and showing the line number within the File Review page. The dropdown box controls the number of lines of context to be displayed before and after the line in question: setting it to 0 will remove the context completely. Note that this setting is saved in your session as the default until you log out (or change it).

Next on the window is a text area for adding a comment - the effect of this depends on whether you're adding a new comment, editing an existing comment, adding a review comment or recording an action comment (these latter 2 take place during and after the review meeting, respectively). You must click the button to save your comment.

Note that your comments can include links to other web pages, to files on a filesystem, to Java classes in this review project in JCR, or to any file in the project in JCR. See links in notes and comments for the formats accepted.

At the review stage, you can optionally indicate what type of action is required. If you don't, this will typically be done at the Review meeting.

Under the text area is a list of any comments already attached to this line of the file, including the owner of the comment and when it was added. Depending on the project state, there may also be a review comment, required action, action owner, action comment, and an indicator of whether the action is complete.

There are also action links available on the existing comments:

• If you're the owner of a comment, and the project state allows, you'll be able to edit or delete the comment. The administrator can do this to anyone's comments
• If the project is in the 'Review meeting' state, you can add or update a review decision. This allows you to add a review comment, select the action required, and/or select the person to be responsible for carrying out the action
• If the project is in the 'Post review' state, you can add an action comment, and click a checkbox to indicate that all required actions have been carried out.

The menu at the top of the pop-up allows you to:

• Scroll backwards or forwards to the previous or next comments in the project (not just this file), using the sort order you chose on the Project page. This is particularly useful during review meetings - just leave the pop-up open, and scroll through all project and file comments that way.
  • Hovering the mouse over one of these links shows the file line number or thread name it leads to, as well as the position of the file or project comment thread in the sorted list, and the total number of file lines with comments/project comment threads
  • Note that an asterisk (*) is added to the Next or Previous link label if it will take you to a different file, or to a project comment
  • At the Review Meeting and Post Review stages, if you clear the 'Show even if no action required' indicator, only comments requiring action will show in the dialog, and the Next and Previous links will only navigate to those requiring action.
• Jump to the comment line in the review file. This brings up the File Review page in the window that launched the popup (if it's not already there), and scrolls it to the line your comment relates to.

Tip: If you have the screen real-estate (e.g. with dual monitors), it's useful to leave the comment dialog open. This makes the review process faster.

The following shortcut keys can be used:

• Alt + m - Move to next comment
• Alt + o - Move to previous comment
• Alt + s - Select the comment line in the review file window.

Project comment dialog

This dialog is almost exactly the same as the File comment dialog, with the following differences:

• This dialog relates not to file comments on a line in a file, but to project comments for a single thread. A thread is just a topic for discussion, like on a message board
• Instead of lines of context from a file, this dialog shows the thread title. If you're creating a new thread it's editable, otherwise it's read-only. However, you can make the title editable by clicking on 'Edit title'.
• There is no 'Select in file' equivalent.

File Comments page

This page shows all the comments for a single file. You can get to it by clicking on the 'File comments' link from the File Review page.

As with the File comment dialog, you can choose the number of lines of file context to show either side of the code for each comment, although this defaults to 0 (no context at all) since it's a bit slower to do this for lots of comments than it is for one.

All the comments display, along with any review decisions, review comments, action comments etc. The same actions are available here as on the File comment dialog, i.e. edit comment, review decision etc. depending on the project state.

Clicking on the file name takes you to the top of the File Review page for the file, while clicking on the line number for a comment takes you to that line in the File Review page.

The 'Show even if no action required' toggle link allows hiding all those comments that require no further action, i.e. either the action is marked as complete, or the review decision was 'No action required' or 'Comment incorrect'. This is useful in the post-review state, when completing the actions, and is not available until this stage of the project's lifecycle.

If the project is in the post-review project state, a checkbox shows alongside each comment, to allow you to record whether you've completed all actions associated with the comment. This is just a shortcut - if you want to add an action comment at the same time as you record the completed actions, you should still click on the 'Record action' link. If you use the checkboxes, remember to click the 'submit' button afterwards to save your changes.

Project Comments page

This page shows all the comments for a whole project, and is reached from the 'All comments' menu item on the Project page. It is almost exactly the same as the File Comments page, except that surprisingly enough it shows all comments for the project, including both project comments (at the top) and file comments. The sort order from the project page is used to order both types of comments.

Status Report page

This page, reached via the 'Status report' menu item on the Project page, shows a snapshot of the status of the project. It's intended as both a quick summary for users (especially project owners), and as a printable screen to record compliance with any processes that are being audited.

Apart from general project details, the report shows:

• Timestamps for each change of status of the project
• Numbers of comments, actions required and actions yet to be completed, by reviewer
• Numbers of comments, actions required and actions yet to be completed, by file (note that this doesn't include project-level comments).

The file section also shows a column indicating the amount of review activity on the file, as a score - the higher the number, the more times the file was viewed or commented on. The scores are the total score for the file for each reviewer - see file review scores below for details of how these are calculated. NOTE: These scores include all access to each file, at all stages of the review project.

File View page

This page is used to show the code of a file that hasn't been included in the project for review, or that has been selected for display using the View any file page. For a Java file, you are most likely to get here by clicking on a class link when viewing another Java file, either in the File Review page or in the File View page for another class.

It's much like the File Review page, except that there are no links for comments.

The following shortcut keys can be used:

• n - Move to start of next diff chunk
• p - Move to start of previous diff chunk.

View Any File page

This page is accessible from the menu on the Project or File Review pages, and allows for searching for and viewing any modified, added or deleted file within the project.

Enter a search string for the whole file path (case-sensitive), and click 'Search'.

You can use the following wildcards in the search string:

• * matches any number of characters
• ? matches any single character
• [AaBbCc] matches any single character in this list (in this case A-C or a-c).

Click on the link to view the file in the File view page.