Have Others Review Your Code

Code that makes sense to two people is more likely to be correct than code that makes sense to one. If you an a colleague made a practice of reading each other's code, it is likely that both of you would be repaid by spending less time debugging your work.

Although I have known people who benefited from informally showing each other their work, if would probably be better if your organization had a formal review or inspection process. There is more than one way to do this. I think, your guiding principle should be to choose something that people in your organization can be comfortable with rather than to try to figure out what's "best".

To help convince you that some form of review process can be valuable, here are excerpts from a discussion that took place in the newsgroup comp.software-eng in August of 1995. The discussion involved both nuances of kinds of reviews and inspections as well as the value of having some form of review process. These excerpts address only the latter point.

The first of my excerpts is from a posting by myself:

"I want to add a point that is often overlooked. In the decade or so that I have looked over code of practicing programmers, I have found that the ones who write the cleanest code have been thru some sort of an inspection or review process -- even if that process was just an informal passing of code back and forth between two guys in an office. So, if management wants code that is maintainable as well as correct, some form of inspection or review processes is mandatory."

Excerpted from a posting by Edward Hartnett:

I agree with this and am posting to point out that this is often a management problem.

Excerpted from a posting by D. Dale Gulledge:

"However, if you are in an organization that already does code reviews, and you are seeking ways to get more out of them, this might be an excellent point to raise. It has been my experience in being on both the authoring and reviewing end of quite a few code reviews, that they rarely catch a significant fraction of the bugs still in the code. However, I have learned a number of things about coding style that have made my code more readable.

Excerpted from a posting by Karla Johnson:

"I suspect that many managers and developers simply don't realize that the object of a review proceeding is not to point fingers at individuals but simply to spot potential problems before they become magnified in scope and cost."

Excerpted from a posting by Mark Terribile:

"I was part of a group of programmers who pressed management for a code review system. We got an informal review process and the curve of broken-by-fix bugs collapsed to the axis. Well, almost."

Excerpted from a posting by Martin Tom Brown:

"Inspections are well worthwhile, preferably matching people of different abilities so that a range of ideas and errors are explored. Many programmers do not criticise constructively, or take criticism well which is unfortunate as the quality gains are there to be had. In formal reviews you have to be careful to manage the process or it can quickly degenerate ..."

Excerpted from a posting by Alain Lapalme:

I'll echo most of Martin's comment.

Excerpted from a posting by Stephen Baynes:

"Anyone who claims they write perfect code is deluding themselves and is hazard to anyone else involved (using or maintaining) the code. We do 'code read's on almost all code, and it works ..."

"I have experienced the introduction of s/w inspections in two organizations now... In my experience at both of these companies have resulted in a significant decrease in bugs at all stages following the inspecitions. Inspections were implemented at requirements, design, and implementation.

However, these reductions were not made as a direct result of the discovery of bugs (or defects if you will)... [Instead, inspections make people more careful and the greater awareness of what other people are doing leads to fewer coordination problems]"

These excerpts all are in favor of some form of review process, but not necessarily in favor of the same form of review process. When I have noticed similar discussions in comp.software-eng, dissenting comments have been few and far between. I believe the few dissenting comments arose from mismanaged review processes.

Indeed, these excerpts and the postings from which they were taken indicate all forms of review will fail if mismanaged. One difficult problem is to permit management to extract some information from the process without using the process for employee review. Using the process for employee review is bad because, when the employee salaries depend on the way they review each other's work, the review sessions tend to degenerate into a bunch of people trying to score points against each other.

So, if you are thinking of introducing a formal review process, take the time to study the experience of others. Here are some sources.

1. An article by Fagan is the source that started most people moving.

2. Fagan latter wrote a follow up article.

3. My favorite source on the subject is a book written by Freedman and Weinberg.

4. In addition, Weinberg has his own web site.

5. Another good source is a book by Ebenau and Strauss.

Copyright 1995,1996 by J Adrian Zimmer

This tip is distributed to individuals free of charge from the Internet Themes web site. All other distribution (including but not limited to internal distribution within an organization and mirroring of any kind) is forbidden without written consent of the copyright holder.

Return to the top of this document.