This article continues Part 1 of the series, where we began the code review process by demonstrating some ways to find the best candidate files to review. We then introduced some techniques to identify what code a specific developer had written, using some of the features in the Versioning Toolbox. The next task is to actually comment on the code. This is always best done in an electronic format, in a way that can be pulled together with other developers’ comments during the code review meeting.

Using Code Annotations to Write Review Comments
The Code Annotations feature in the Editing Toolbox is extremely useful for writing code review comments because it lets you attach comments to specific locations in the code without altering the code itself. You can bring up the Code Annotations tool window by clicking SlickEdit > Show Code Annotations.

[Click for full size image]

The first step when writing code review comments is to create an annotation file to store all of your code review comments. You can then send this file to the code review organizer when you’re done. You can use the Annotation File Manager to create a file called “Code Review – Bob” (or whatever your name may be).

Writing Comments About the Code
After applying the “Scott’s code” visualization scheme that we made in the first article, we can navigate through the sections of code that Scott has written. On line 497 of PackageBaseWhidbey.cs, we see that he’s doing a GUID comparison using a literal string. This goes against coding standards, so we’ll log a comment that the string literal needs to be defined as a constant. Put the cursor on that line and click the New Annotation button on the Code Annotations toolbar. This will bring up the New Annotation dialog.

We’ll create a review comment, which is one of the standard annotation types. We’ll also select the “Global : Code Review – Bob” scope, or category, which will put the annotation into the code review file we created earlier. After filling out the fields and clicking OK, a purple highlighted marker is placed on the line of the new comment.

[Click for full size image]

Once you create an annotation, it gets an entry in the annotation list. You can select that entry to see a summary of the annotation, or you can double click on it to jump directly to the code it is assigned to. This makes it easy to get to the code that you’ve commented on.

We also found a bug on line 431 of FileUtility.cs, so a bug annotation can be logged for that. This new annotation has a red highlight to indicate that it’s a bug type.

[Click for full size image]

It’s helpful to only show annotations that you have created for the code review, without the clutter of others in the list. You can filter out all non-code review annotations by using the Annotation Filter Configuration dialog, available on the code annotations toolbar. Select Filter by Scope and select the “Global : Code Review – Bob” item. Now, only your code review annotations will be visible in the list.

Wrapping Up Your Review
Once all of your code review comments have been completed, they will all be contained in the file “Code Review – Bob.sca“, which we created at the beginning of the article (code annotation files have an extension of .sca by default). That file can then be sent to the code review organizer.

All of the received code annotation files can then be imported by the organizer during the code review meeting, where they can be discussed. Reviewing code this way maintains a tight link between the code review comments and the actual source code, and is far better than trying to manage the process with pen and paper, or a set of text documents.

You can also create a report of the annotations to print before the meeting, or to send to other developers. To do this, click the View annotation Detail toolbar button. The Code Annotation Details dialog will be shown and each annotation in the list will be shown in the report. A small red document icon will appear by each annotation that may be clicked to navigate to that annotation in the source code. The report can be exported to HTML or printed.

[Click for full size image]

The next step will be the actual code review meeting, which will be the focus of part 3 of this series. Once the code annotation files are pulled together from all of the reviewers, those comments can be discussed and updated. After the code review meeting, they can be exported to a single code annotation file and emailed back to the group. The developer being reviewed then has a clear set of action items as a result of the meeting.