Developer’s guide to peer reviews

A peer review, sometimes known as a code review or walkthrough, is a thorough technical and logical line-by-line review of a code module (program, subroutine, object, method, etc.). During a peer review, code is inspected to identify possible improvements and ensure that business requirements are met. If necessary, a meeting is held to discuss any issues that come out of the review process.

Although some programmers complain that the reviews take too much time, the drawbacks are usually outweighed by the benefits, such as fewer bugs, less rework, more pride, and better team communication and cohesiveness. This guide will outline some of the positives and negatives of the process and offer some tips on how to make your reviews more productive for your development team.

How does it work?
Peer review methodologies are as numerous as the companies that write code, but most follow a basic three-step model consisting of preparation, review, and follow-up. Here’s a look at each step.

Preparation
First, the code being reviewed must be complete, tested by the programmer, and in the programmer’s view, ready for the next step in the development life cycle. The code and other affected project components, such as documentation, test cases, a project schedule, or requirements changes must also be available to the review participants. Participants should review the code and other materials prior to the meeting and come prepared to discuss their issues without having to read the material again during the meeting. Of course, the date, time, and location of the meeting should be established in advance.

Review
Reviews are conducted as needed, usually based on the rate of code output. The frequency of individual participation in a peer review depends primarily on the size of the programming team. A team of three programmers might include all three in every review. Larger teams might be able to rotate participation based on experience, skill level, subject matter familiarity, or site-unique factors.

If possible, the review should include the programmer, two reviewers, a recorder, and a leader. Still, even if only one other programmer can review code, he or she should do so. Other considerations for the size of the review team might be the scope of the project, workload, or training needs.

Some questions reviewers might bring up—and which the programmer must be ready to discuss—include the following:

• How does this module actually satisfy the stated business requirement?
• Wouldn’t a case statement work here instead of a nested if-then-else structure?
• How does the output affect the previously base-lined interface documentation?

All participants should be open-minded and willing to discuss issues in a straightforward manner. The programmer needs to recognize that the suggested changes are not personal attacks, and the reviewers need to recognize the programmer’s pride of authorship. The team leader has the authority to decide which suggestions will be implemented. The leader also uses the meeting to stay involved and aware of what the team members are doing. Someone should be designated to document the proceedings.

The meeting might go like this: The leader opens with a short discussion of the goal of the meeting and lays out any ground rules. The programmer explains his or her code, what it’s supposed to accomplish, what requirements it contributes to, and what documentation it affects. Each participant raises questions, comments, and suggestions identified in the preparation phase. The programmer addresses those issues and explains the logic, problems, and choices that resulted in this code.

Follow-up
Follow-up provides evidence of the meeting’s success and incentive for the continued use of reviews. The value of future reviews will be degraded if decisions are not enacted, and eventually programmers will view the process as just another waste of time. Follow-up is critical for all participants, especially the programmer. The documentation must be kept in a central location where anyone can reference it.

The reviewers should also look at the review as a learning experience. By seeing what types of issues are brought up, they can address those issues in their own code. The team leader should always be open to feedback from the participants to identify ways to improve the meetings and team unity.

Benefits
What benefits can you expect from using the peer review process with your code? A few of the benefits include:

• A different perspective. “Another set of eyes” adds objectivity. Similar to the reason for separating your coding and testing teams, peer reviews provide the distance needed to recognize problems.
• The ability to assess and accelerate progress. Is the team producing the needed output at the needed rate?
• Pride/reward. Recognition of coding prowess is a significant reward for many programmers.
• Project/module familiarity. Everyone involved in the review becomes more familiar with the project and the module.
• Less rework. Do it right the first time. Changes cost more later in the life cycle. The peer review process catches many errors before they go to production.
• Fewer bugs. It’s better to discover your own problems than to have someone (like a user) point them out to you. For the same reason, you may find that many bugs will be eliminated before the code comes to be reviewed by peers.
• Improved communication. More opportunities for interaction tend to lead the team toward improved communication.
• Team cohesiveness. Working together helps draw team members closer. It also provides a brief respite from the isolation that coding often brings.

Challenges
It can’t all be roses. A few of the issues you will need to balance when you implement peer reviews include:

• Time. Some peer reviews take a long time. But like other types of meetings, focusing on the topic, being familiar with the process, and establishing solid ground rules can help keep the time reasonable (less than an hour). Peer reviews invest your time; bugs waste it.
• Preparation. Reading unfamiliar code and correlating that code to unfamiliar documentation takes programmers away from coding. However, it’s a necessary evil. Over time, however, proper preparation for the meeting should take less time, as reviewers learn what to look for and become familiar with the process.
• Initial frustration. If team members are not familiar with peer reviews, the experience can be frustrating for all participants. Teams need to devise a process for peer reviews, implement it, and modify it only when the situation dictates. In time, members will grow accustomed to the process.
• The need to show commitment. Although random peer reviews offer some benefit, that level of commitment is questionable. Your goal should be to conduct a peer review for every module.

How to conduct better reviews
Like any skill, good peer reviews come with practice. Some tips that should help you get started on the right track are as follows:

• Don’t create a battleground. The goal is better software, not who’s right.
• Lay out the ground rules. Which review comments must be addressed before proceeding in the life cycle? What are valid reasons for missing a review? Who can cancel a review?
• Maintain professionalism. Don’t take the criticism personally and offer only technical advice that will improve the code. Respect others’ opinions, comments, and suggestions.
• Be careful with the scope of the review. Determine the size range or the scope of the code being reviewed. Too large, and the whole process takes too long; too small, and you’ll have so many reviews you won’t have time left to code. Also, define the size and composition of your normal review team, as described earlier.
• Document what happens. Write everything down, especially decisions and action items.
• Take a class on software inspection. Maybe you have an in-house code review expert, or perhaps one team member could read a book and then train the rest of the team. Consider using the local college/university or contact corporate training institutions to bring a trainer on-site.
• Commit to the process. Maybe you tried conducting a review and it didn’t work. Try it again. And again. Commit to the process and you will reap the benefits.

Go forth and review
Peer reviews can be a fun and interesting part of the development process. There may be a few drawbacks, but the end result is usually better code, and better code is good for everyone. Additionally, you may even find that as the reviewer or the reviewed, your skills as a developer will grow.