Let's Do a Code Review With SlickEdit Tools (Part 2)
This article continues Part 1 of the series, where we set out to code review a developer named Scott. 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 changing the code file 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 use the Annotation File Manager to create a file called "Code Review - Bob" (or whatever your name may be).
We'll start by applying the "Scott's code" visualization scheme that we created in Part 1 of this series. This allows us to navigate through the sections of code that Scott has written, which are highlighted in red, since we're interested in reviewing only his code.
[Click for full size image]
Writing Comments About the Code
While navigating Scott's code, we found a section he wrote with 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. We'll 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, 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. Each annotation entry shows who created it, what file and line number it's located on, when it was created and when it was last modified. You can select that entry to see a summary of the annotation in the right hand pane, 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.
As a second example, we've found a bug in another code file, so a "bug" annotation can be logged for that. This new annotation has a red highlight to indicate that it's a bug type of annotation.
[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 now 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.
Take It for a Spin
At SlickEdit, we are confident that you will be as excited about the latest release of SlickEdit® Tools 2.0 for Microsoft Visual Studio as we are. Download the trial version and try it out for yourself.
