Code Is Not Literature

An anonymous reader writes "Hacker and author Peter Seibel has done a lot of work to adopt one of the most widely-accepted practices toward becoming a better programmer: reading high quality code. He's set up code-reading groups and interviewed other programmers to see what code they read. But he's come to learn that the overwhelming majority of programmers don't practice what they preach. Why? He says, 'We don't read code, we decode it. We examine it. A piece of code is not literature; it is a specimen.' He relates an anecdote from Donald Knuth about figuring out a Fortran compiler, and indeed, it reads more like a 'scientific investigation' than the process we refer to as 'reading.' Seibel is now changing his code-reading group to account for this: '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.'"

Comments

Yeah I Could See That

[Greyfox]

I've read a lot of code over the years and thinking back on it, I do kind of approach it that way. What I'm doing feels more akin to taking a machine apart to see how it works rather than reading it as I would a book. I often feel, when I'm interrupted, like I'm ass-deep in wires that are going every-which-way.

It is still a method of communication, though. You can often tell a lot about the programmer and his state of mind at the time by reading his code. It's very easy to tell when they were confused about what they were trying to accomplish, how comfortable they were with the language they were using and whether or not they were in a hurry.

Early on in my career, I started with the assumption that the original programmer knew what he was doing. The more code I read, the more I realized that this is almost never the case. From my observations, it takes about a year for someone to come up to speed with a project, the business process for the company they're working at, and any code base that was already there. Longer if the company's business processes suck. Until then they're mildly to severely confused, and this is reflected in their code. Since a lot of programmers don't hang around at one company for much longer than that, most of the code that I've run across has been crap. The first inclination might be to rewrite it, but as you're starting on a new project you're also mildly to severely confused, so it's best just to study the crap closely and make minor improvements as the opportunities arise. A crap in the hand is worth two in the bush. Or something. Most of the time. I've run across a couple of what had to have been bottom-ten-percent programmers whose crap did end up requiring full rewrites. Coming into a C project where the programmer didn't realize strings are null terminated is a huge warning. C++ or Java code where everything inherits from everything else is also a warning.

Re:What?

[cold fjord]

Your comment reminds me of this bit about the code for what became Adobe Photoshop. The code is available for download from a link on the page linked to below.

Adobe Photoshop Source Code

Thomas Knoll, a PhD student in computer vision at the University of Michigan, had written a program in 1987 to display and modify digital images. His brother John, working at the movie visual effects company Industrial Light & Magic, found it useful for editing photos, but it wasn’t intended to be a product. Thomas said, “We developed it originally for our own personal useit was a lot a fun to do.” Gradually the program, called “Display”, became more sophisticated. In the summer of 1988 they realized that it indeed could be a credible commercial product. They renamed it “Photoshop” and began to search for a company to distribute it. ... The fate of Photoshop was sealed when Adobe ... decided to buy a license to distribute an enhanced version of Photoshop. ....

Commentary on the source code
Software architect Grady Booch is the Chief Scientist for Software Engineering at IBM Research Almaden and a trustee of the Computer History Museum. He offers the following observations about the Photoshop source code:

“Opening the files that constituted the source code for Photoshop 1.0, I felt a bit like Howard Carter as he first breached the tomb of King Tutankhamen. What wonders awaited me? I was not disappointed by what I found. Indeed, it was a marvelous journey to open up the cunning machinery of an application I’d first used over 20 years ago. Architecturally, this is a very well-structured system. There’s a consistent separation of interface and abstraction, and the design decisions made to componentize those abstractions – with generally one major type for each combination of interface and implementation — were easy to follow. The abstractions are quite mature. The consistent naming, the granularity of methods, the almost breathtaking simplicity of the implementations because each type was so well abstracted, all combine to make it easy to discern the texture of the system. . . .

This is the kind of code I aspire to write.”

Good examples can provide powerful learning experiences. They can crystalize the intangible aspects of description and discussion.

Re:Similar language, describing different things

[Stormy Dragon]

Please demonstrate a basic sorting algorithm that a non-programmer can understand that doesn't perform terribly on large lists. You might be able to write a bubble or insertion sort that makes sense to a layman, but for the majority of the population something like mergesort, quicksort, or heapsort is going to seem like voodoo no matter how elegantly it is coded.

Re:Well parts are like literature

[Greyfox]

But but but! A mechanical object can be beautiful, and so can code! Often I've seen brilliant and occasionally sadistic approaches to the problem that I can definitely appreciate at an artistic level. Something like Duff's Device requires both technical brilliance and a good amount of creativity. I have to read and analyze code for my job on a regular basis.

A mechanic must know his way around a car to know how to repair it, and I must know my way around the code base if I am to diagnose problems. I can't just focus on the broken parts of it, or changes I make will likely introduce side effects. On most of my projects I didn't even have a requirements document, just a big pile of usually-poorly-written code. Each program is a unique individual machine, as if every single car were built dramatically differently. How much harder would it be for a mechanic if they had to go hunting for the spark plugs before they could even get started?

Knuth disagrees

[phantomfive]

Knuth disagrees, which is why he created Literate Programming. If you aren't familiar with it, you should make yourself familiar. He suggests eventually someone might win a prize for literature from their code.

If you haven't seen it, you should check it out. His code has a table of contents, and could definitely be considered literature. His Tex code is so well organized, that you can find what you are looking for within 15 minutes, even if you're not really familiar with it. That's how code should be: written so other people can read it.

That's not what the author is talking about, though. He's talking about crappy code that wasn't written in a way that was easy to understand (I read the article; this is my understanding of it). So yeah, crappy code is not literature, or easy to 'decode.' Tautological.