3.5. Reviewing Topics

3.5.1. Viewing a Topic

The "View Topic" screen is one of four tabs available for viewing aspects of a topic. An example "Topic Text" tab display can be seen in Figure 3-5.

The top bar contains the following links to other Codestriker pages:

The next part of the screen shows the four available tabs for viewing different aspects of a topic. The "Topic Comments" tab is for viewing the comments that have been submitted against the topic. Clicking on this tab will take you to the "Topic Comments" page (see Section 3.6). The "Topic Properties" tab takes you to a page where you can view and edit the topic's attributes, such as the title, author, reviewer, the repository the code in the review has been made against, the project the review is associated with, and the topic description. Clicking on this tab will take you to the "Topic Properties" page (see Section 3.7). Finally the "Topic Information" tab contains topic metric data, both user-defined and entered, and those that can be automatically derived by Codestriker. Clicking on this tab will take you to the "Topic Information" page (see Section 3.8).

Following the "Download topic text" link will return in the browser the raw topic text which was entered when the review was created. This can be useful if the raw diff needs to be retrieved, so it can be used as a patch file. There are some links which affect the display, such as whether a mono-space font should be used to render the code changes (requires more screen real-estate), whether to preserve the code's line-breaking or not, and what tab-width to use.

This is followed by the table of contents of the review, which consists of the list of files which comprise the topic, whether they are added, removed or modified files, appropriately colour-coded. If a file has been modified, the revision of the file that has been modified is displayed. If filename is clicked, the browser will move to the anchor which corresponds to changes made to that file.

The rest of the "View Topic" page can be seen in Figure 3-6.

This shows the start of the code changes for the file codestriker/codestriker.pl. Clicking on the filename will show revision history of this file, if Codestriker has been configured to link with a system, like ViewCVS. The "Go To Contents" link will move the browser back to the table of contents.

From this point, the screen in split into two sections, where the left side represents the old version of the file, and right side represents the new version. In the figure, the code in the block of red represents code which has been removed in the proposed change. Adjacent yellow blocks represent code changes, as can be seen with the version number change. The green block represents new code which has been added, in this instance, the new constants for viewing modes.

Each file is broken up into a series of "deltas". At the head of each delta block, for both the old and new versions of the file, there is an indication of what line number the delta started at. In this situation, clicking on the "Line 24" link on the left hand side, will open a new browser window, which will contain the complete original contents of codestriker/codestriker.pl, anchored at line 24. Clicking on the "Line 22" link on the right hand side will contain the complete contents of codestriker/codestriker.pl will all of the proposed changes applied. Clicking on "Parallel" will do a similar job, but will show both the original and new version of the complete file side-by-side. See Section 3.5.3 for more details on what can be done with these complete file-based views, which can assist enormously in the review process.

3.5.2. Adding a Comment

Every line of code in the display, is prefixed with a hyperlinked number. This number represents the line number of the file. If a comment needs to be made against a specific linenumber, click on the linenumber, and floating window will come up with the "Add Comment" page (see Section 3.5.2). If a comment has already been made against a line, it will be red. Hovering over the line will bring up a tooltip window, containing the details of the comment made.

A comment against a line is made by clicking on the line number of interest. This will display a floating window, an example can be seen in Figure 3-7.

As can be seen in the figure, the window contains a text box where the comment can be entered. Any formatting will be preserved, so that you can enter new code fragments, if required. Any comment metrics defined in the Codestriker configuration will appear here as a series of dropdown boxes. In this example, there is only the comment metric "Status" defined. As before, your email address is remembered in the browser's cookie, to prevent you from having to enter it each time you make a comment. When the "Submit" button is pressed, an email will be generated and sent to the author of the review, to the email address in the "Your email address" field as a reference, to the email address in the "Cc" field, just in case there is a requirement to send the email elsewhere, and to any other email addresses that have made a comment on this line, so that it is possible to get a form of discussion happening.

Once the comment has been accepted by the server, it will be automatically dismissed. If there was an error processing the comment, an error message will be displayed at the top of the window.

3.5.3. Viewing Complete old/new Files

As mention in Section 3.5.1, it is possible to view the entire contents of a file in a review in its original form, or in its proposed form, or side-by-side depending on whether the "Line" or "Parallel" link was selected. The review has to be linked to a SCM repository, so that it can fetch parts of the file which aren't a part of the review text.

When a "Line" link is clicked, a new browser window will come up with the contents of the file. This will be slow the first time, but in subsequent times will be fast since the browser window is not closed. An example of this window can be seen in Figure 3-8.

This view matches the new contents of codestriker/codestriker.pl, from the "View Topic" screen seen in Section 3.5.1. Each corresponding delta will have consecutive hyperlinked line numbers. Those lines which do not have a hyperlinked line number are outside the deltas in the review, but are a part of the file. Clicking on a hyperlinked line will bring the "Add Comment" window into display, in the same way it would as if the line number was clicked from the "View Topic" screen.

Seeing the entire contents of a file, either pre or post change is often essential to complete a review properly. Sometimes, it is necessary to see both versions of the file side-by-side. An example can be seen in Figure 3-9.

The same rules apply for adding comments - any hyperlinked line number can be clicked in order to add a comment.