Talk About Quality

Tom Harris

Really simple code review tool

with 3 comments

I know what I want: highlight-and-comment capability in a text editor. And since plain text really shouldn’t be marked up, I’d want it to save the comments in a separate text file, with line numbers of what was commented on, and the comments’ text. I’m not the first one looking for this capability: “climbanymountain” asked about it on Joel on Software back in 2006: “win32 text editor for code review?

I started thinking about writing a plugin for some popular text editor, such as Notepad++ or Notepad2 (the latter is my favorite for simple editing). But before the “build or buy” decision, I thought I’d ask around the office.

A lot of ideas, but here was the simplest. Light and off-the-shelf. Use a diff tool. 

The following procedure works fine, and “supports” any version control system. In my example, I’m using open-source WinMerge as my diff tool, IBM Rational ClearCase as my version control system, and Microsoft Windows Explorer as my tree browser. Say the source file to review is called “MyFile.c”, and the reviewer’s name is Firstname Lastname.

The parts in square brackets are optional: omit them if you don’t want to clutter up your version control system with code review records, but just want to use them to prepare for sitting with code author.

  1. Browse to the source code file I want to review; [check it out and] open it.
  2. Immediately Save As MyFile_flastname_review.c in the same directory. Close the source code file.
  3. Select the source code file and the review file (they are next to each other in alphabetical order), right-click and open WinMerge on them.
  4. Go to the pane of the review file and type review comments anywhere I want. Save regularly with CTRL-S. (Optionally, for better syntax highlighting, can precede comments with comment character such as “//”. But don’t have to.)
  5. Generate a diff (patch) file, call it the same name as the review file, but add .diff on the end. (In WinMerge, that’s on the menu with Tools > Generate a patch.)
  6. [Check in all 3 files (adding 2 new ones to source control) — check-in activity per defect tracking system, and comment with one-line summary of the review.]

From this point, code review comments are easily viewable side-by-side with the code by viewing in WinMerge or similar viewer.

Also, the diff file clearly identifies the line number commented on, and the comment text. I figure I could write an AWK script to turn that into CSV, for tabular display and tracking in Microsoft Excel, if I wanted to.

Written by Tom Harris

June 17, 2009 at 11:38 am

Posted in Code Review

3 Responses

Subscribe to comments with RSS.

  1. Why not check out the beta of Crucible 2? You get highlight-and-comment capability in a browser! It does all that and a bit more: http://blogs.atlassian.com/news/2009/06/crucible_2_beta.html

    Not much simpler..

    Ken

    Ken Olofsen

    June 20, 2009 at 3:46 am

  2. You may want to check out our Tools for Visual Studio product. It has a feature called Code Annotations that allows you to store notes, or annotations, about your source code. All annotations are stored in separate files, without modifying your source code files, just like you wrote about. It also has advanced searching and filtering when your annotation list gets long. There are a handful of predefined annotation types, such as Bug, Comment and Task, but you can make your own types and specify what fields you want to store.

    You can check it out here (http://www.slickedit.com/content/view/486/content/view/486) and download a trial. You can also check out a set of articles I wrote here about how to use Code Annotations, and other Tools features, as part of a full code review (http://www.codeproject.com/KB/showcase/CodeReviewPart2.aspx)

    Scott H

    July 2, 2009 at 10:19 pm

  3. Hi Tom – you bring up an interesting point.

    For lightweight code review, we provide Code Reviewer, a simpler version of our flagship product (Code Collaborator).

    At the moment, we’re running a special: $5 for 5 seats of Code Reviewer, for five days only (July 13-17). Details here: http://smartbear.com/code-review-5-for-5.php.

    We’ll also be doing a webinar on July 15 to show off the features of Code Reviewer: http://smartbear.com/webinar-schedule.php

    Gregg Sporar

    July 13, 2009 at 4:43 pm


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s