CS 372 Spring 2016  >  Notes for February 26, 2016

CS 372 Spring 2016
Notes
for February 26, 2016

Code Review

What Code Review Is

Code review, or more properly peer code review, is the process by which one developer checks the code that another developer has written or changed.

Typically, it goes something like this. Developer A is working on some issue. When this work is finished, Developer B look at Developer A’s work, without Developer A being present. Developer B asks questions like the following.

• Does the code conform to standards (style guidelines, etc.)?
• Does the code contain any logic errors?
• Is the code sufficient? Does it allow the project to fully meet the requirements that motivated the change?
• Are the associated tests sufficient?
  • Do new tests need to be written, to handle the changed code?
  • Do existing tests need to be rewritten, to account for the changes?

When Developer B with the review, the results are communicated to Developer A.

The Value of Code Review

It is widely agreed that code review is a highly beneficial practice. A quote from Jeff Atwood.

I believe that peer code reviews are the single biggest thing you can do to improve your code.

GGC adds: it can improve your coding skills as well.

From Code Complete, 2nd ed. by Steve McConnell, pp 480–481.

Technical reviews have been studied much longer than pair programming, and their results, as described in case studies and elsewhere, have been impressive.

...

• In a software-maintenance organization, 55 percent of one-line maintenance changes were in error before code reviews were introduced. After reviews were introduced, only 2 percent of the changes were in error. When all changes were considered, 95 percent were correct the first time after reviews were introduced. Before reviews were introduced, under 20 percent were correct the first time.
• A group of 11 programs were developed by the same group of people, and all were released to production. The first five were developed without reviews and averaged 4.5 errors per 100 lines of code. The other six were inspected and averaged 0.82 errors per 100 lines of code. Reviews cut the errors by over 80 percent.

See the book for citations for the above claims.

Best Practices

How best to do code review has been studied a great deal, and much has been written about it. There is general agreement on the following ideas.

• Only small segments of code should be reviewed at one time. Recommendations typically suggest something like 200 lines of code, and no more than 400 lines.
• Before the review, the author (“Developer A”, above) should annotate the code. In particular, when beginning the review, the reviewer (“Developer B”, above) should know:
  • What was changed?
  • Why was it changed?
  • Is there anything that needs particular attention from the reviewer?
• Do not rush a review. A well done code review might take an hour.
• On the other hand, a reviewer should not work continuously for long periods of time. Reviewing for more than an hour without a break results in less helpful reviews.
• Reviews should be organized.
  • Reviews should have clear goals.
  • Reviews should be done according to explicitly stated standards.
  • Checklists are helpful. Use them!
• However, review should allow (but not necessarily require) unstructured comments. A reviewer who sees a problem should be free to point it out, even if it is not a violation of any particular written standard.

Variations

There are other practices that are similar to code review, and have similar benefits.

• Pair programming. The one watching is doing a kind of review of the code the other is typing.
• Author walk-through. Developer A might walk Developer B through some code recently written by Developer A. Curiously, this can be beneficial even if Developer B is not present. The practice of explaining code to someone who is not present, or to an inanimate object, is sometimes called rubber duck debugging, The name originated with a story* about a developer who carried around a rubber duck, so that he could explain his code to it.

It should be noted, however, that the above are not code review. They can be beneficial, but they are not the same.

Lastly, we note that some code review is tool assisted. Any number of software tools are available, that are intended to facilitate the code-review process.

Code Review will be continued next time.