Code is not literature

http://www.gigamonkeys.com/code-reading/

I have started code reading groups at the Last II companies I ' ve worked at, Etsy and Twitter, and some folks has asked F Or my advice about code reading and running code reading groups. Tl;dr:don ' t start a code reading group. What do you should start instead I'll get to in a moment if first I need to explain how I arrived on my current opinion.

As a former 中文版 major and a sometimes writer, I had always been drawn to the idea that code was like literature and tha T we ought to learn to write code the the-learn to write English:by reading good examples. And I ' m certainly not the only one to having taken this point of View-donald Knuth, in addition to he work on the Art o F Computer Programming and TeX, have long been a proponent of what he calls literate programming and have published SEv Eral of his large programs as books.

On the other hand, long before I got to Etsy and started my first code reading group I had in hand several pieces of evide nCE that should has suggested to me, this is the wrong-to-look at things.

First, when I do my book of interviews with programmers, coders on work, I asked pretty much everyone about code reading. And while the most of them said it is important and that programmers should does it more, when I asked them on what code th EY had read recently, very few of them had any great answers. Some of them had done Some serious code reading as young hackers but almost no one seemed to has a regular habit of readi ng code. Knuth, the great synthesizer of computer science, does seem to read a lot of code and Brad Fitzpatrick were able to talk AB Out several pieces of open source code, he had read just for the heck of it. But they were the exceptions.

If that wasn ' t enough, after I finished coders I had a chance to interview Hal Abelson, the famous MIT profess Or and co-author of the Structure and interpretation of computer Programs . The first time I talked to him I asked my usual question about reading code and he gave the standard answer-that it is IM Portant and we should do it more. But he too failed to name any code he had read recently other than code he is obliged to:reviewing co-workers ' code at G Oogle where he is on sabbatical and grading student code at MIT. Later I asked him about this disconnect:

Seibel: I ' m still curious about this split between what people say and what they actually does. Everyone says, "People should read code" but few people seem to actually do it. I ' d be surprised if I interviewed a novelist and asked them what's the last novel they had read was, and they said, "Oh, I H Aven ' t really read a novel since I was in grad school. " Writers actually read other writers but it doesn ' t seem the programmers really do, even though we say we should.

Abelson: Yeah. You ' re right. But remember, a lot of times your crud up a program to make it finally work and does all of the things that's need it to do , so there's a lot of extraneous stuff around there this isn ' t the core idea.

Seibel: So basically you ' re saying this in the end and most code isn ' t worth reading?

Abelson: Or it ' s built from an initial plan or some kind of pseudocode. A lot of the code in books, they has some very cleaned-up version that doesn ' t does all the stuff it needs to make it work.

Seibel: I ' m thinking of the preface to SICP, where it says, "programs must is written for people to read and only incidentally for Machines to execute. " But it seems the reality your just described is so in fact, most programs was written for machines-execute and only in Cidentally, if at all, for people to read.

Abelson: Well, I think they start out for people to read, because there ' s some idea there. You explain stuff. That's a little bit of what we had in the book. There is some fairly significant programs in the book, like the compiler. And that's partly because we think the easiest a-to-explain what's it's doing is to express this in code.

Yet somehow even this explicit acknowledgement the most real code isn ' t actually in a form so can be simply read was N ' t enough to leads me to abandon the literature seminar model when I got to Etsy. For your first meeting I picked Jeremy Ashkenas ' s backbone.js because many of the Etsy developers would is familiar with Ja Vascript and because I know Jeremy is particularly interested in writing readable code. I still envisioned something like a literature seminar and I figured that a lot of people wouldn ' t actually has done the Reading in advance (well, maybe does different from a literature seminar) so I decided to start things off by presenting The code myself before the group discussion.

As I prepared my presentation, I found myself falling into my usual pattern while trying to really understand a piece of Code-in order to Grok it I had to essentially rewrite it. I ' ll start by renaming a few things so they make more sense to me and then I'll move things around to suit my ideas about How to organize code. Pretty soon I ' ll have gotten deep into the abstractions (or lack thereof) of the code and would start making bigger changes To the structure of the code. Once i ' ve completely rewritten the thing I usually understand it pretty well and can even go back to the original and Unde Rstand it too. I have all felt kind of bad about this approach to code reading but it's the only thing that's ever worked for me.

My presentation to the code reading group started with stock backbone.js and then walked through the changes I would make To it-make it, by my lights, more understandable. At one point I asked if people thought we should move the group discussion but nobody seemed very interested. Hopefully seeing my refactoring gave people some of the same insights into the underlying structure of the original that I Had obtained by doing the refactoring.

The second meeting of the Etsy Code reading group featured Avi Bryant demonstrating how to use the Code browsing Capabilit IES of Smalltalk to navigate through some code. In this case, because few of the Etsy engineers had any experience with Smalltalk, we had no expectation that folks would Read the code in advance. But the presentation is an awesome chance for folks to get exposed to the power of the Smalltalk development environment And for me to heckle Avi about Smalltalk vs Lisp differences.

When I got to Twitter I inexplicably still had the literature seminar model on mind even though neither of the II meeting S of the Etsy reading Group-which folks seemed to like pretty well-followed. When I sent out the e-mail inviting Twitter engineers to join a code reading group The response is pretty enthusiastic. The first meeting is, yet again, a presentation of some code, in this case the internals of the Scala implementation of F Uture that's used throughout Twitter's many services, presented by Marius Eriksen, who wrote the most it.

It was sometime after, presentation that I-finally realized the Obvious:code is not literature. We don ' t read code, we decode it. We examine it. A piece of code is not literature; It is a specimen. Knuth said something that should has pointed me down this track when I asked him on his own code reading:

Knuth: But it's really worth it builds in your brain. So how does I do it? There is a machine called the Bunker Ramo and somebody told me that the Fortran compiler for this machine is really Amazingly fast, but nobody had any idea why it worked. I got a copy of the Source-code listing for it. I didn ' t has a manual for the machine, so I wasn ' t even sure what is the machine language is.

But I took it as an interesting challenge. I could figure out and then BEGIN I would start to decode. The operation codes had some Two-letter mnemonics and so I could start-to-figure out "This probably is a load instruction , this probably is a branch. " And I knew it is a Fortran compiler, so at some point it looked at column seven of a card, and the was where it would te ll if it is a comment or not.

After three hours I had figured out a little bit on the machine. Then I found these big, branching tables. So it is a puzzle and I kept just making little charts like I ' m working @ A security agency trying to decode a secret co Beh But I knew it worked and I knew it is a Fortran compiler-it wasn ' t encrypted in the sense of it was intentionally Obscu Re It is only in code because I hadn ' t gotten the manual for the machine.

Eventually I was able to figure out why this compiler is so fast. Unfortunately it wasn ' t because the algorithms were brilliant; It is just because they had used unstructured programming and hand optimized the code to the hilt.

It was just basically the the-the-solve some kind of a unknown puzzle-make tables and charts and get a little more inform ation here and make a hypothesis. In general when I ' m reading a technical paper, it's the same challenge. I ' m trying to get into the author's mind, trying-to-figure of what's the concept is. The more you learn to read other people's stuff, the more able your is to invent your own in the future, it seems to me.

He ' s not describing reading literature; He ' s describing a scientific investigation. So now I had a new mode for what people should get together to gain insights from code which I explained to the Twitter Co De reading group like this:

Preparing for the talk I ' m going to give to the Girls who Code cohort, I started thinking on what to T Ell them about code reading and code they should read. And once again it struck me that for all the lips service we pay to the idea of reading code, most programmers really don ' t Read that much code in least not just for the sake of reading it. As a simple proof:name me one piece of code, you ' ve read and so you can is reasonably sure that the most other good pro Grammers would have read or would at least has heard of. Not many, right? Probably None.

And then it hits me. Code is not literature and we were not readers. Rather, interesting pieces of code is specimens and we are naturalists. So instead of trying to pick out a piece of code and reading it and then discussing it like a bunch of Comp Lit. Grad students, I think a better model is for one of us-play the role of a 19th century naturalist returning from a-trip To some exotic-present to the local scientific society a discussion of the crazy beetles they found: ' Look at t ' He antenna on this monster! They look incredibly ungainly but the male of the species can use these to kill small frogs in whose carcass the females l ay their eggs. "

The point of such a presentation are to take a piece of code, the presenter have understood deeply and for them The audience understand the core ideas by pointing them out amidst the layers of evolutionary detritus (a.k.a. kluges) tha T is also part of almost all code. One reasonable approach might be-show the real code and then-to-show a stripped down reimplementation of just the key B Its, kind of type a biologist staining a specimen to make various features easier to discern.

The ideal presentation should is aimed at a audience of gentleman and Lady Programmers-smart, and generally capable but w Ithout, necessarily, any specific knowledge of the domain from which the code comes. Presentations should provide enough context for the audience-to-understand what the code was and should explain any deta Ils of the implementation language that may is obscure to the average programmer.

Since I had my epiphany we ' ve had several meetings of the Code reading group, now known as the Royal Society of Twitter FO R improving Coding knowledge, along the new lines. We ' re still learning about the best ways to present code and the model feels very right. Also, I no longer feel bad on my dissection-based approach to reading code.

The biggest lesson is very dense. A half hour presentation is just enough time to present maybe a dozen meaty lines of code and one main idea. It is also almost certainly the case that the presenters, who has to actually really dig down into a piece of code, get m Ore out of it than anybody. But it does seem, a good presentation can at least expose people to the main ideas and maybe give them a head start if They do decide to read the code themselves.

Code is not literature