del.icio.us .:. tweet

Code Review using the Clarion Method .:. kentbrewster.com

Background: the Clarion Science Fiction and Fantasy Writers' Workshop is the best known and most highly regarded science fiction writing workshop in the world. The Clarion Method was refined from the original Milford Writers' Workshop method by Damon Knight, founder of the Science Fiction and Fantasy Writers of America, for critiquing short stories submitted over the course of an intensive six-week "boot camp" for new writers.

Clarion's mission is simple but awesome: seventeen to twenty participants need to a) have their say on up to five thousand words of fiction in b) under two hours, while c) not causing the author whose work was under the microscope to shriek and run out of the room, pull out a pistol and begin firing, or otherwise stop listening to critique.

Many parallels may be drawn between code review and fiction critique. Some shared goals include improving the specific work in question, granting the author different perspectives on the work before it goes into production, teaching the same lessons to attendees whose work is not currently under review, and--most important--creating a common vocabulary of critique among all members of the group. Here's how it works:

  • The work in question is distributed in identical format to all participants. This is critical; everybody should have the same page and line numbers to refer to. When distributing print-outs of what something looks like on a Web browser, please be sure to print a screen capture (Print-Screen, paste to Photoshop) and print that, rather than trusting any particular Web browser to print properly.
  • Everyone reads the source and/or runs the work before the session begins. (This is also critical; nothing screws things up worse than somebody who's paging through a manuscript, speed-reading it, and critiquing it as he goes along.)
  • A moderator is on hand to run the session. The moderator's job is to keep time, gently correct participants who break the rules, and deliver a summation of what's been said about the work in question.
  • During the session, each participant except the author of the work delivers a three-minute review of the work. Play proceeds from the author's right and goes all the way around the table, skipping the moderator, who should go last.
  • Critique should center on the work itself, not the author's choice to do the work in the first place. Not helpful: "I don't know why the hell you're bothering trying to support IE5 on a Macintosh." "XMLHttpRequest breaks the whole paradigm of the Web!" "Ick, I can't believe you're using .NET!"
  • If something's already been mentioned, participants should not go over it again. They should feel free to say stuff like "dittoing what Mike said about that nested set of ordered lists," but otherwise should not waste time.
  • If everything's already been said, participants should feel free to run down a list of things they ditto and say "Done."
  • Participants should not pass, unless they have not read or do not understand how the work in question operates. If that's the case, they should say so, and not give the author the impression that they're lurking until the very end.
  • During the initial round of review, the author of the work must remain completely silent. (At Clarion, a stuffed animal is made available for the victim author to hug, strangle, or otherwise express his or her emotions during critique; this may or may not translate well to code review.)
  • Review must stop at three minutes. The moderator should deliver quiet one-minute and thirty-second warnings, and then say "time" when it's time. The participant speaking should stop talking as soon as possible. Thre minutes might not sound like a lot of time, but multiply that by six or seven other participants and you get a tremendously long time for the author to remain silent.
  • After the initial round, the author gets to ask as many questions as he wants. The moderator needs to keep a grip on this part; it should not turn into a free-for-all until the author has enough information about what the review meant.
  • Finally it's time for the free-for-all. If there's another work awaiting review the moderator should set a time limit here; otherwise, break out the beer and fire away.

If all of this goes according to plan, everyone will have his say about the work, the author will hear it all without feeling overwhelmed or interrupted, and the resulting brainstorming session should ease the sting of having the work dissected before an audience and encourage creativity.

We've been running Clarion-style code reviews among a small group of Yahoo! Web developers for a couple of months years now and it seems to be working out reasonably well. Personally I've learned to write much more accessible HTML, much tighter CSS, and to always be aware of when I'm coding something that's not going to validate. I'd love to hear from others who've been using formal code review methods; please fire away, if you're one of them.

I'd also dearly love to hook up with a group outside of work; face-to-face networking opportunities are few and far between, and a monthly gathering for code, pizza, and beer would be Outstanding.

Comments from before Disqus:

Copyright Kent Brewster 1987-2014 .:. FAQ .:. RSS .:. Contact