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

I have started code reading groups at the last two companies I’ve worked at, Etsy and Twitter, and some folks have asked for my advice about code reading and running code reading groups. Tl;dr: don’t start a code reading group. What you should start instead I’ll get to in a moment but first I need to explain how I arrived at my current opinion.

As a former English major and a sometimes writer, I had always been drawn to the idea that code is like literature and that we ought to learn to write code the way we learn to write English: by reading good examples. And I’m certainly not the only one to have taken this point of view—Donald Knuth, in addition to his work on The Art of Computer Programming and TeX, has long been a proponent of what he calls Literate Programming and has published several 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 evidence that should have suggested to me that this was the wrong way to look at things.

First, when I did my book of interviews with programmers, Coders at Work, I asked pretty much everyone about code reading. And while most of them said it was important and that programmers should do it more, when I asked them about what code they 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 have a regular habit of reading code. Knuth, the great synthesizer of computer science, does seem to read a lot of code and Brad Fitzpatrick was able to talk about several pieces of open source code that 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 professor 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 was important and we should do it more. But he too failed to name any code he had read recently other than code he was obliged to: reviewing co-workers’ code at Google where he was 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 do. 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 the last novel they had read was, and they said, “Oh, I haven’t really read a novel since I was in grad school.” Writers actually read other writers but it doesn’t seem that programmers really do, even though we say we should.

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

Seibel: So basically you’re saying that in the end, 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 have some very cleaned-up version that doesn’t do all the stuff it needs to make it work.

Seibel: I’m thinking of the preface to SICP, where it says, “programs must be written for people to read and only incidentally for machines to execute.” But it seems the reality you just described is that in fact, most programs are written for machines to execute and only incidentally, 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 have in the book. There are some fairly significant programs in the book, like the compiler. And that’s partly because we think the easiest way to explain what it’s doing is to express that in code.

Yet somehow even this explicit acknowledgement that most real code isn’t actually in a form that can be simply read wasn’t enough to lead me to abandon the literature seminar model when I got to Etsy. For our first meeting I picked Jeremy Ashkenas’s backbone.js because many of the Etsy developers would be familiar with Javascript and because I know Jeremy is particularly interested in writing readable code. I still envisioned something like a literature seminar but I figured that a lot of people wouldn’t actually have done the reading in advance (well, maybe not so 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 when trying to really understand a piece of code—in order to grok it I have 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 will 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 understand it too. I have always 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 to make it, by my lights, more understandable. At one point I asked if people thought we should move on to 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 capabilities of Smalltalk to navigate through some code. In that 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 was 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 in mind even though neither of the two meetings of the Etsy reading group—which folks seemed to like pretty well—followed that model at all. When I sent out the email inviting Twitter engineers to join a code reading group the response was pretty enthusiastic. The first meeting was, yet again, a presentation of some code, in this case the internals of the Scala implementation of Future that is used throughout Twitter’s many services, presented by Marius Eriksen, who wrote most of it.

It was sometime after that 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 have pointed me down this track when I asked him about his own code reading:

Knuth: But it’s really worth it for what it builds in your brain. So how do I do it? There was a machine called the Bunker Ramo 300 and somebody told me that the Fortran compiler for this machine was 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 have a manual for the machine, so I wasn’t even sure what the machine language was.

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

After three hours I had figured out a little bit about the machine. Then I found these big, branching tables. So it was a puzzle and I kept just making little charts like I’m working at a security agency trying to decode a secret code. But I knew it worked and I knew it was a Fortran compiler—it wasn’t encrypted in the sense that it was intentionally obscure; it was only in code because I hadn’t gotten the manual for the machine.

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

It was just basically the way you solve some kind of an unknown puzzle—make tables and charts and get a little more information 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 out what the concept is. The more you learn to read other people’s stuff, the more able you are 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 have a new mode for how people should get together to gain insights from code which I explained to the Twitter code reading group like this:

Preparing for the talk I’m going to give to the Girls who Code cohort, I started thinking about what to tell them about code reading and code they should read. And once again it struck me that for all the lip service we pay to the idea of reading code, most programmers really don’t read that much code, at least not just for the sake of reading it. As a simple proof: name me one piece of code that you’ve read and that you can be reasonably sure that most other good programmers will have read or will at least have heard of. Not many, right? Probably none.

But then it hit me. Code is not literature and we are not readers. Rather, interesting pieces of code are 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 to play the role of a 19th century naturalist returning from a trip to some exotic island to present to the local scientific society a discussion of the crazy beetles they found: “Look at the 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 lay their eggs.”

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

The ideal presentation should be aimed at an audience of gentleman and lady programmers—smart, and generally capable but without, necessarily, any specific knowledge of the domain from which the code comes. Presentations should provide enough context for the audience to to understand what the code is and should explain any details of the implementation language that may be 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 for Improving Coding Knowledge, along the new lines. We’re still learning about the best ways to present code but the model feels very right. Also, I no longer feel bad about my dissection-based approach to reading code.

The biggest lesson so far is that code 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 have to actually really dig down into a piece of code, get more out of it than anybody. But it does seem that 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的更多相关文章

  1. [渣译文] 使用 MVC 5 的 EF6 Code First 入门 系列:为ASP.NET MVC应用程序创建更复杂的数据模型

    这是微软官方教程Getting Started with Entity Framework 6 Code First using MVC 5 系列的翻译,这里是第六篇:为ASP.NET MVC应用程序 ...

  2. MVC 5 的 EF6 Code First 入门

    英文渣水平,大伙凑合着看吧…… 这是微软官方SignalR 2.0教程Getting Started with Entity Framework 6 Code First using MVC 5 系列 ...

  3. [翻译][MVC 5 + EF 6] 5:Code First数据库迁移与程序部署

    原文:Code First Migrations and Deployment with the Entity Framework in an ASP.NET MVC Application 1.启用 ...

  4. 用 MVC 5 的 EF6 Code First 入门 系列:MVC程序中实体框架的Code First迁移和部署

    用 MVC 5 的 EF6 Code First 入门 系列:MVC程序中实体框架的Code First迁移和部署 这是微软官方SignalR 2.0教程Getting Started with En ...

  5. MVC3+EF4.1学习系列(一)-------创建EF4.1 code first的第一个实例

    基于EF4.1 code first 简单的CRUD  园子中已经有很多了 ~~ 真不想再写这个了 可是为了做一个完整的小demo 从开始 到后面的一些简单重构 还是决定认真把这个写出来 争取写些别人 ...

  6. [渣译文] 使用 MVC 5 的 EF6 Code First 入门 系列:建立一个EF数据模型

    英文渣水平,大伙凑合着看吧…… 这是微软官方教程Getting Started with Entity Framework 6 Code First using MVC 5 系列的翻译,这里是第一篇: ...

  7. MVC5使用EF6 Code First--创建EF数据模型(一)

    此Web应用程序演示如何使用Entity Framework 6和Visual Studio 2015创建ASP.NET MVC 5应用程序.本教程使用“Code First ”即代码先行.有关如何在 ...

  8. 使用 MVC 5 的 EF6 Code First 入门 系列:建立一个EF数据模型

    这是微软官方SignalR 2.0教程Getting Started with Entity Framework 6 Code First using MVC 5 系列的翻译,这里是第一篇:建立一个E ...

  9. 在.net core中数据操作的两种方式(Db first && Code first)

    在开发过程中我们通常使用的是Db first这种模式,而在.net core 中推荐使用的却是 code first 反正我是很不习惯这种开发模式 于是就搜寻整个微软的官方文档,终于找到了有关.net ...

随机推荐

  1. X-UniTMX:导入大型Tiled地图文件(*.tmx)到Unity3d中比较好的插件

    因工作原因,需要导入格子数为1200x1200的Tiled地图文件(*.tmx)到Unity3d中显示出来.尝试过一些其它插件,后面发现X-UniTMX是比较好用的. X-UniTMXhttp://f ...

  2. 1029c语言文法2理解

    program → external_declaration | program external_declaration <程序>→ <外部声明>|<程序>< ...

  3. uva514(trail)(模拟栈)

    //#define LOCAL #include<cstdio> #include<cstring> #include<cstdlib> #include<s ...

  4. 漫谈iOS Crash收集框架

    漫谈iOS Crash收集框架   Crash日志收集 为了能够第一时间发现程序问题,应用程序需要实现自己的崩溃日志收集服务,成熟的开源项目很多,如 KSCrash,plcrashreporter,C ...

  5. Java 集合系列 17 TreeSet

    java 集合系列目录: Java 集合系列 01 总体框架 Java 集合系列 02 Collection架构 Java 集合系列 03 ArrayList详细介绍(源码解析)和使用示例 Java ...

  6. Java 容器(集合)

    import java.util.*; 一.基础概念 1.什么是容器? 2.为什么需要容器? 3.容器的分类? 二.重点知识 List接口 Collections类 (1)为什么需要? Collect ...

  7. ThoughtWorks微服务架构交流心得

      ThoughtWorks微服务架构交流心得: (1)<人月神话>中谈到软件开发没有银弹,根源在于软件所解决的领域问题本身固有的复杂性,微服务正是从领域问题角度上进行服务拆分,来降低软件 ...

  8. Git 提交大文件提示 fatal: The remote end hung up unexpectedly

    使用gitlab搭建的git server,如果直接使用http的方式去提交的话,提交小文件不会有问题,但是提交大文件时,会出错: fatal: The remote end hung up unex ...

  9. 如何在Hadoop的MapReduce程序中处理JSON文件

    简介: 最近在写MapReduce程序处理日志时,需要解析JSON配置文件,简化Java程序和处理逻辑.但是Hadoop本身似乎没有内置对JSON文件的解析功能,我们不得不求助于第三方JSON工具包. ...

  10. 常州培训 day2 解题报告

    第一题: 题目大意: 给出一个M面的骰子,投N次,求最大期望值. 最大期望值的定义: 比如M=2,N=2, 那么 2次可以是 1,1,最大值为1: 1,2最大值为2: 2,1最大值为2: 2,2 最大 ...