Emma Jane Westby

Six Ways to Make Your Peer Code Reviews More Effective

OSCON 2013 Speaker Series

NOTE: If you are interested in attending OSCON to check out Emma Jane’s talk or the many other cool sessions, click over to the OSCON website where you can use the discount code OS13PROG to get 20% off your registration fee.

The critique is a design school staple. You can find more than a few blog posts from design students about how “the crit” either made them as a designer, or broke their will to live. Substitute “critique” with “code review” and you’re likely to find just as many angst-filled blog posts in the open source community. Or, more likely, you’ll notice a lack of contributors following a particularly harsh text-based transaction.

Somewhere along the way we dropped one of the original meanings of the word “critique”. According to Wikipedia, a critique is “a method of disciplined, systematic analysis of a written or oral discourse”.

A good critique is more than just a positive feedback sandwich that wraps “negative” feedback between two slices of “positive” feedback. An effective critique needs to have three components in place to be successful:

  1. An agreed-upon framework for the evaluation.
  2. Reviewer objectivity.
  3. A creator uncoupled from his or her work.

The Quantitative Review

Quantitative reviews are the easiest to conduct. And, generally, coding standards for a project are quantitative. A quantitative review answers questions such as: Is this code formatted according to coding standards? Does the code cause any performance regressions? Quantitative evaluations can be easily measured. The code being reviewed is either right, or non-compliant. The findings of quantitative reviews are generally hard to argue with. (Ever tried to pick a fight with Jenkins?) Having a quantitative framework in place often means that your project will also be able to free up reviewer time by putting automated tests in place. Which leaves time for a more difficult type of review: the qualitative review.

The Qualitative Review

A framework for a qualitative review is incredibly difficult to create because there is space for subjective thought as it addresses the values of a project. There is room for opinion. Two people could be right at the same time, even though they are not at all in agreement. Qualitative frameworks are so difficult to create that most projects don’t even try; however, an effective qualitative framework helps both the coder and the reviewer to improve their skills. A qualitative framework teaches non-experts what attributes they should be looking for in the code they are reviewing. Questions posed during a qualitative review may include: Does this code implement a pattern we’ve already seen somewhere in the project? Has the code been sufficiently abstracted to make it reusable in other situations?

Read more…