Code Reivews

Code reviews are the most effective way of making sure your code has a minimum number of bugs. Code reviews not only give you better code but also give you better programmers.

Producing an effective code review is an art. It requires good people skills and management support. It takes time to get a good system in place.

The first thing to consider when planning a code review is who will be on the team doing the review. Ideally you should try to have three to five people there in addition to the person who wrote the code. Less than three and you don't have enough people to do an effective review. More than five and you can't have an effective meeting. (In large meetings people don't talk, they give speeches.)

At least one senior software engineer should be part of the group. He's there to make sure that the code being review conforms to the overall design of the project it's written for. He also has enough experience so that he probably can spot more problems than the less experience coders.

Ideally, you probably don't want management there. That's because whenever a non-technical boss shows up you spend more time explaining things to him than reviewing code. If a manager decides he must be there make sure he knows that his role is strictly as an observer.

One problem with code reviews is getting the team to actually attend the meetings. Bribery is one solution to this problem. Free drinks, cookies, bagels or other eats can be used to help attendance. Lunch should also be considered.

All right, you've chosen the team, you've got a conference room, and somehow managed to get everyone into the meeting what now.

First, you need to designate someone to take notes. This person's job is to capture all the important information generated in the meeting. This person should not be the writer of the code. He should keep is own notes. That way with two sets of notes you can be sure that any changes recommended by the committee are performed.

The meeting starts by with the author of the code explaining his work. How he does it is largely irrelevant. He can use the top down method, bottom up, or sideways with a left twist. As long as the other people in the room understand what he's done he can do it any way he wants to.

The other people in the room should feel free to break into the conversation at any time with questions, suggestions, or when they notice a problem.

Comments should be constructive. Everything said should go to making the code better. Such things like, "I think you need to check for an error return from that system call," fall into this category.

Things like, "I could have done that in half as much code," are not. This is not a competition. This is also not a design review, so don't criticize the design (unless it's flawed and will absolutely not work.)

It is important to keep the meeting on track. The purpose of the review is to make sure the code works. It's not to anything but the code in front of you. Topics like new programming techniques, the latest Microsoft product, and what movie you saw last night do not belong here. They should wait until your regular gossip sessions when you and the rest of the boys hang around the copy machine to discuss the latest rumors.

Code reviews should last about one to two hours. Three at the most. Any longer than that and the committee will start to skim code and skip steps just to get out of the meeting. Programmers are like a can of coke: after about three hours they go flat and lifeless.

If you need more time, break it into multiple review. Preferably with different people doing the review each time.

If you do a review right, the result will be that you've caught a number of errors. But what's important is that those errors did not make it into the final product. Fixing something in the testing stage or worse after the product has shipped is extremely costly.

But the real savings are yet to come. The next time the programmer writes something he will have the benefit of knowing what mistakes he made last time and will be able to avoid making them again. So not only do code reviews generate better programs, the make better programmers.