Blog by Sumana Harihareswara, Changeset founder

15 Dec 2014, 11:06 a.m.

A Code Review Group

Hi, reader. I wrote this in 2014 and it's now more than five years old. So it may be very out of date; the world, and I, have changed a lot since I wrote it! I'm keeping this up for historical archive purposes, but the me of today may 100% disagree with what I said then. I rarely edit posts after publishing them, but if I do, I usually leave a note in italics to mark the edit and the reason. If this post is particularly offensive or breaches someone's privacy, please contact me.

I'm interested in piloting a peer code review group, structured like a writer's group. So next month I'm starting one out in New York City, starting with Hacker School alumni and participants, and I figured I'd put some logistics and reasoning here for my own future reference and to help anyone who'd like to do something similar.

Basics: Part of the point of a writers' group is to get participants to produce work consistently, and part of the point is to help everyone learn craft -- the authors and the critiquers. So I'm trying out a similar structure for this pilot. We will meet in person; I think that criticism is often a lot easier to take in person, and I know it's easier for me to take in person. We'll meet about every 3 weeks, midday Saturday or Sunday, to critique two works of code. We'll have a rotating schedule of who's responsible for writing code and who's responsible for reviewing it; I am maintaining that schedule. (I'm copying the frequency and format from writers' groups like Leonard's.) I figure we'll run this with about 5-6 people for four months, hopefully giving each person a chance to have their code reviewed twice, and then reevaluate and see what to keep, change, or give up.

Who?: It felt natural to me to start this in the Hacker School community. Anyone who's going or gone to Hacker School is someone who accepts the social rules we've set up to make learning easier, and is generally collaborative and friendly. Also, alumni can use Hacker School for stuff like this outside of normal work hours, which means we can use a HS conference room (and projector!) for the group meetings.

What language?: Since Python is the only language I am fluent in and it is the language I'd prefer to work in and grow in, most code we review will be in Python. I consider myself an intermediate Python programmer (very comfortable writing list comprehensions, but still need to stop and look up exception-handling syntax when I need it; see "mcmasala" for a recent code sample). Fortunately, Python's enough of a lingua franca, and there's a wide enough variety of skill levels in the Hacker School community in New York, that several programmers were willing to sign up to an intermediate-and-higher Python-specific group. After the pilot period, I think the group will evaluate the idea of expanding to other languages, and see how we feel about skill heterogeneity.

New code only?: I'm not sure whether people will end up submitting already-written or fresh code for the group to critique. I personally think that it would be fine to circulate bespoke and/or already-working-on-it code. Sometimes I might be working on something that's so huge that it doesn't make sense to extract a small-enough chunk of it for peers to review, so I'd write something from scratch instead. Sometimes I'd really want my peers to look at something that I have already been noodling with. I'm curious what other code review groups have found when experimenting on this axis.

Submission length?: My current wild-ass guess is that each submission for review should be somewhere between 32 and 2048 lines of code, but, given that (as in import this) is ~6 lines other than a giant string, I am happy to deal with codebases of lengths 4-31 as well, for the length of the pilot. :)

Time commitment?: As far as I can tell, here's the format and time commitment for this pilot:

  • Everyone: in-person meeting every three weeks for about four months, January-April -- probably about 60-90 minutes long each time, with about 30-45 minutes for each work (the critiquers offering praise and criticism of the work, and the author responding at the end).
  • Per person: Twice during the pilot: writing code and emailing it (or a link to it) to the rest of the group, a week ahead of the meeting.
  • Per person: Before every meeting, so, about 5 times: reviewing the author's or authors' code ahead of time and writing out notes, so it's easier to give specific praise and criticism at the meeting, and to email to the author(s) afterwards. (I say "author's or authors'" because even if you're one of the two authors who submits code for a particular meeting, you'll still have to review the other author's code for that meeting.) Writing a critique will probably take the participant at least 30 minutes per critique.
  • Organizer: a few hours total of scheduling, sending nag emails, and writing writeups like this one. :)

I'm opening comments on this post specifically to hear from other people who have participated in code review groups, about what has worked and not worked for you. And of course other people should feel free to reuse bits of these ideas to start groups that meet online, or go multilingual, or meet more or less frequently, or what have you!


Sumana Harihareswara
16 Dec 2014, 9:07 a.m.

Thanks to Andromeda Yelton for pointing me to Coral Sheldon-Hess's Code Club which is at least partially based on another idea that has more details at Reading Code Good.

Helen Halbert
20 Dec 2014, 19:07 p.m.

Thanks for posting this (and the links to similar groups)! I just created a meetup for women in tech and while we're not a code club per se, it's nice to know what other groups are up to and what formats might work for different folks in the group.