Code Readings: Douglas Crockford's secret to software teams that punch above their weight

I recently came across a gem of an idea in a Douglas Crockford interview with Peter Seibel, from Seibel’s Coders at Work. The idea is that of a code reading: a public presentation of code that’s a sort of cross between a code review and a tech talk and a whiteboard session.

As Crockford tells it, code readings sound pretty awesome: the mentorship effect of a great code review, multiplied across all involved team members, at cost of maybe a half-hour or an hour per week. Not to mention the predictability gains, the trust-building, and the practice opportunity for technical speaking in a setting with a lower technical bar than, say, a brown-bag tech talk.

Have any teams besides Crockford’s Yahoo! group put this into practice? I’d love to learn about your experience.

Below is the text of the relevant excerpt from Crockford’s interview:

Seibel: These days you’re a JavaScript architect and evangelist here at Yahoo!, so part of your job, presumably, is to tell Yahoo! JavaScript programmers, “Here’s how you should do it.” Does your job also cover general good design practice and good coding practice?

Crockford: One of the things I’ve been pushing is code reading. I think that is the most useful thing that a community of programmers can do for each other—spend time on a regular basis reading each other’s code. There’s a tendency in project management just to let the programmers go off independently and then we have the big merge and if it builds then we ship it and we’re done and we forget about it. One of the consequences of that is that if you have weak or confused programmers you’re not aware of their actual situation until much too late. And so the risks to the project, that you’re going to have to build with stuff that’s bad and the delays that that causes, that’s unacceptable. The other thing is that you may have brilliant programmers on the project who are not adequately mentoring the other people on the team. Code reading solves both of those problems.

Seibel: Can you talk a bit about how you conduct a code reading?

Crockford: At each meeting, someone’s responsible for reading their code, and they’ll walk us through everything, and the rest of us will observe. It’s a really good chance for the rest of the team to understand how their stuff is going to have to fit with that stuff. We get everybody around the table; everybody gets a stack of paper. We also blow it up on the screen. And we all read through it together. And we’re all commenting on the code as we go along. People say, “I don’t understand this comment,” or, “This comment doesn’t seem to describe the code.” That kind of stuff can be so valuable because as a programmer you stop reading your own comments and you’re not aware that you’re misdirecting the reader. Having the people you work with helping to keep your code clean is a huge service—you find defects that you never would’ve found on your own. I think an hour of code reading is worth two weeks of QA. It’s just a really effective way of removing errors. If you have someone who is strong reading, then the novices around them are going to learn a lot that they wouldn’t be learning otherwise, and if you have a novice reading, he’s going to get a lot of really good advice. And it shouldn’t be something that we save for the end. Back in the old days, we would schedule a code reading just as we were finishing a project and it would be canceled because we were late. I now believe that code reading should be happening all the time throughout the life of the project. That’s something that took me a while to figure out but there are so many benefits that come from that.
For one thing it makes it easier to track the project because we can actually see what progress people are making. and we can see much sooner if they’re going off the rails or not.
I’ve managed projects where we were up against a deadline and we had people saying, “Yeah, I’m almost done,” and then you get the code, and there’s nothing there, or it’s crap, or whatever, and they’re nowhere close to done. In management, those are the experiences you have the most and I think code reading is the best way of not getting trapped like that.

Seibel: So say we’re doing a code reading of some of my code. I bring printouts and we put it up on the screen. Then what? Do I literally read it out loud?

Crockford: Yeah, go through it line by line, and you’ll be doing commentary on it. This is what’s supposed to be happening here. If we have time, we’ll go line by line.

Seibel: Do you find that you have to teach people how to do code readings? I can imagine it’d be hard to find the right balance of being critical enough to be worthwhile without making the code’s author feel personally attacked.

Crockford: Yeah, it requires a lot of trust on the part of the team members so there have to be clear rules as to what’s in bounds and what’s not. If you had a dysfunctional team, you don’t want to be doing this, because they’ll tear themselves apart. And if you have a dysfunctional team and you’re not aware of it, this will reveal it pretty quickly. There’s a lot that you can learn, a lot that’s revealed by this process. It feels unnatural at first, although once you get into the rhythm of it, it feels extremely natural. Another aspect is writing your code such that it can be read. Neatness counts, as it turns out, and style is important. And all of those things will increase the quality of the code base going forward and increase the competence of the programming community.