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.

Coding is as much of an art as writing literature. It’s a forgotten sentiment in programming these days. It’s easy to get lost in the sea of API’s, libraries, frameworks, and everything that’s out there that must be understood before you can start to program effectively. But many programmers see this as the end. Once they learn how to use an API, their learning is considered complete until the next required API comes along.

Just like a novelist must have a solid foundation of grammar and vocabulary, a good programmer must understand the fundamental APIs for their language. But a novelist cannot write a novel with grammar and vocabulary alone. It takes creativity to turn the words into a meaningful connection with the reader. The equivalent of this in programming is usability for the end user.

Usability is such a bad word. Dictionary.com defines it as “capable of being used”. Thanks for that. However, scrolling down further, it also references the following as it relates to programming:

The effectiveness, efficiency, and satisfaction with which users can achieve tasks in a particular environment of a product. High usability means a system is: easy to learn and remember; efficient, visually pleasing and fun to use; and quick to recover from errors. [1]

Now we’re getting somewhere! This is a perfect analogy to the novelist trying to connect to the reader. Investigating further, I found the HCI (Human Computer Interface) page at Wikipedia. I was expecting to find the softer side of programming, sort of a feel good, warm milk and teddy bears approach to software. However, I pretty quickly realized that it’s a whole other science in itself.

After creating what I think are some really compelling features in our Tools product, I’m having to look back on it now and figure out how to optimize it for the user. That’s so hard to do when you’ve worked with a thing for so long, or even worse if you’ve created the interface to it. Just like I wrote in my “Zen Mind, Programmer’s Mind” post, I really need to go back and approach it as it I knew nothing about it. I’ve always approached HCI by imagining the way that I would want to use it. It’s so easy to forget that I’m just one person and there will be so many more people out there using my software that won’t agree with the way I use it.

HCI is fairly new to me, but I’m always interested in learning something new. The problem to me is how amorphous it is. There are principals, guiding rules, methodologies, and such, but there are no concrete steps. I guess that’s how it is though when you get into the areas of programming that make the leap from straightforward answers to creative problem solving.

I wonder if someday in a hundred years or so we’ll talk about software like we talk about classic literature now. Maybe someday there will be a Shakespeare or a Mark Twain of software. Maybe someday you’ll be able to see a piece of software and say that it’s a distinctive program for a particular developer group. The closest thing we have to that right now is Apple. Someday I hope I can look at may own software and think, “Yeah, that was my style.”

1. The Free On-line Dictionary of Computing, © 1993-2007 Denis Howe

In writing software, there are a few words you see in your symbol names more than any others:

• First, Last
• Next, Previous
• Begin, End
• Push, Pop
• Draw, Erase
• Add, Remove
• High, Low
• Yes, No
• Stop, Go
• OK, Cancel
• And, Or
• Up, Down
• Left, Right
• True, False
• In, Out
• Plus, Minus
• Fixed, Floating
• Open, Close

Each pair is opposite in meaning and different in length. When I study these pairs of words, I can’t help but be absolutely convinced that the inventors of the English language gave absolutely no consideration to the fact that (thousands of years later) there will be millions of programmers writing code in mono-spaced fonts and really, really wanting it to line up nicely, but thwarted by this lack of similarity in length.

If you are smart, you’ll stop reading now, the rest is a bit predictable and boring. The point of this article is that it is annoying to write code that looks like this.

So much is it annoying, that the monosyllabic, four letter abbreviation “Prev” has nearly became a universally accepted substitute for “Previous”, within the confines of software, at least.

You are still reading? Ok, fine. Really, if you have been programming at all, you have already encountered this, and you know everything I’m going to say. You could have stopped at the title, in fact.

There are a few exceptions to this rule of opposites — Get, Set, North, South, East, West, Insert, Delete, Internal, External, Throw, Catch. Get and Set are so loved, I think for their matching size and rhyme, that we have invented new words for those types of functions (getters and setters). Of course, “setter” isn’t a new word, but prior to the explosive discovery that both get and set had three letters, a “setter” usually referred to a breed of canine. What is really impressive are the applications you might find map directions applied to. Not in SlickEdit, but elsewhere, I have seen North and South used for cursor movement where you would have logically used Up and Down. Likewise, East and West have been applied to where you might logically think Left and Right and even, Next and Previous. My theory is that to some, alignment is a worthy cause, so much so that you may chose a naming scheme which involves a level of indirection.

Certain shell languages have employed mirror spellings of keywords as a level of indirection between opposites and like-sized keywords. Thus you find do, od, if, fi, case, esac. The first time you see it, you will think, “What is an esac? If it’s anything like an email, I do not want to touch it.” But, it may grow on you, as the Bourne shell has grown on Unix.

Acronyms were all the rage in the old days when it really did matter that your code be small and fit on a punch card. Some continue to survive and are frequently used, such as Gt for greater, Lt for less than, Eq for Equal, Ne for inequality, Hi for high, Lo for low, T for true, F for false. Sometimes you see hybrid abbreviation pairings, such as Up, Dn, or Add, Del.

Some programming language designers have addressed this issue with more symbols. APL is well known for it’s elaborate character set, “⌊” for floor and “⌈” for ceiling, for example. C++ introduced operator overloading and programmers followed that path of slow, destructive insanity towards standardizing — and ++ as next and previous iterator methods, among others.

But, in the end, this problem of opposites being different is not a programming language issue, it is a natural language issue. It’s a problem with the English vocabulary. And there is little we can do about that. Until we find a natural language invented by linguists who really thought about writing code in monospace fonts, our code will never be aligned as well as it could be.