3.5. Reviewing Topics

Reviewing a topic is achieved by going to the "View Topic" screen for a specific review topic. This can be accessed from either the "Topic List" screen (Section 3.2), or from a URL in a new topic notification email, which is sent to the author and reviewers.

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.

Figure 3-5. View Topic Screenshot

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

List open topics

Following this link will take you to the "Topic List" page (see Section 3.2), and will display all open topics in the system.

Create new topic

Following this link will take you to the "Create Topic" page (see Section 3.4).


Following this link will take you to the "Topic Search" page (see Section 3.9).


Following this link will show this help text.

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.

Figure 3-6. View Topic Detail Screenshot

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.

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 a new browser window will come up with the "Add Comment" page (see Section 3.5.2). This may take some time the first time, as a new browser window needs to be created. After the comment has been entered, the main browser window is displayed, and the comment window is not closed, so that for subsequent comments, the add comment window can be displayed quickly.

3.5.2. Adding a Comment

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

Figure 3-7. Add Comment Screenshot

As can be seen in the figure, a summary of the topic title is displayed, followed by a text box where the comment can be entered. Any formatting will be preserved, so that you can enter new code fragments, if required. 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.

Any comments already made (if any) against this specific line will then be displayed. The screenshot shows one comment has already been made against this code line. The code line the comment is being made against is then displayed. The "increase" link can increase the amount of context code to display, while "decrease" will decrease the amount of context code. The code line in question will be highlighted in red.

Once the comment has been submitted, the main "View Topic" window will be displayed so that the review can quickly continue. If a new comment needs to be added, the comment browser window will be bought back quickly into focus.

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. Like the "Add Comment" window, 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.

Figure 3-8. View File Screenshot

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.

Figure 3-9. Parallel View File Screenshot

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