Kent Brewster’s Clarion Method for Code Reviews

Have a code review coming up? Need to give your peers a thorough review of their code, but are dreading the drudgery of the process? Don’t find the peer review process particularly effective?

There are volumes and volumes written about code review processes, including debates with paired programming and other Agile practices.

Here’s a simple yet powerful alternative. It comes from a former colleague and uber developer: Kent Brewster. As a published author, he’s used the Clarion Method as a process for “critiquing short stories submitted over the course of an intensive six-week ‘boot camp’ for new writers.”

During a team meeting one day, as we hunkered down for a traditional code review, he suggested this alternative. In a nutshell:

Roles

  • Moderator
  • Code Reviewee
  • Code Reviewers (two or more)

Process

  1. Code Reviewee brings printed copies of the code to be reviewed (preferably with a maximum of 10 pages or so). Each participant gets a copy. Each line of code should be numbered.

  2. Code Reviewee provides a high-level summary of the code. This can include the code’s purpose, known bugs, and a brief rationale behind its structure.

  3. Each Code Reviewer reads the code for 5-10 minutes in silence. They can make notes on the copies as necessary. The Moderator keeps track of the time.

  4. Each Code Reviewer takes a 3 minute turn delivering their review. No more than 3 minutes should be spent, as each turn is meant to be quick. If someone else mentions an issue you wanted to raise, just say “ditto on xxx” instead of repeating it.

  5. While the Code Reviewers speak, the Code Reviewee must remain silent. No rebuttals, no explanations, no excuses. Just shut up and sit there. There will be a chance to speak up later.

  6. After the reviews, the Code Reviewee now has a chance to speak. This opportunity should be used to ask questions and clarify what issues the Reviewers saw. Both sides can converse and debate freely now.

Exceptions

  • If the code requires execution to be properly reviewed, each participant can bring a laptop along. The Code Reviewee should provide a location where the code can be seen an executed.
  • If the code is very lengthy, select just one section to be reviewed. Other sections can be reviewed at future sessions.
  • If a Code Reviewer offers incorrect advice, raise it at the end so the Reviewer can learn from this session as well.

Kent has a more detailed explanation of this process on his site.

If done well, this process allows everyone to have a chance to voice their opinions about the code, regardless of their skill level. Code Reviewees and Reviewers alike can learn a lot from these sessions. I’ve even found that developers from across multiple teams can join in without requiring a lot of background information.

Even more telling is that many developers really look forward to their code reviews. This process forms such a supportive, non-threatening, and educational environment that developers know they’ll always learn something new from a code review. That, to me, is a mark of a truly effective process.

Author: Mike Lee

An idealistic realist, humanistic technologist & constant student.

One thought on “Kent Brewster’s Clarion Method for Code Reviews”

Comments are closed.