3.5. Reviewing Topics

3.5.1. Viewing a Topic

The "View Topic" screen consists of a header, followed by the actual code itself. An example header snapshot 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 topic's attributes, such as the title, author, creation date, reviewer, the size of the topic text, the repository the code in the review has been made against the project the review is associated with, and the topic description. If the topic fixes any bugs, the links to the associated bug descriptions will be shown here. The topic's state is also shown here, and can be modified if appropriate, by selected the state from the drop-down list and pressing "Update". If deletion has been enabled, the "Delete Topic..." state will be present in this dropdown, allowing the topic to be deleted.

The number of comments that have been made to this topic is shown next. Clicking on this link will take you to the "View Comments" page (see Section 3.6).

A link called "Download" topic text is shown. Following this 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, and if they are modified, what revision of the file has been modified. 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.

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.

As can be seen in the figure, a summary of the topic is displayed, followed by the code in question. 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.

Any previous comments made on this line will then be displayed. You can enter your comment into the textarea provided. 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.

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.

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 essentially 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.