Peter Seibel - Coders at Work - Reflections on the craft of programming

Seibel:So in this case you wrote the documentation before, or at least while, the code was being written. Is that how you usually do it?

Armstrong:It depends on the difficulty of the problem. I think with very difficult problems I quite often start right by writing the documentation. The more difficult it is, the more likely I am to document it first.

I like documentation. I don’t think a program is finished until you’ve written some reasonable documentation. And I quite like a specification. I think it’s unprofessional these people who say, “What does it do? Read the code.” The code shows me what it does . It doesn’t show me what it’s supposed to do. I think the code is the answer to a problem. If you don’t have the spec or you don’t have any documentation, you have to guess what the problem is from the answer. You might guess wrong. I want to be told what the problem is.

Seibel:Is the documentation you write at this stage internal documentation that another programmer would read or documentation for the user?

Armstrong:It’s for user guides. It sort of switches me into a different mode of thinking. I just start, in order to do this, create a directory called that, put this file in there, rename this as that and that is guiding the structure. I’ve sort of pondered the question. I bet Knuth would say, “Well, all programs are literate programs.” You don’t write the code and then write the documentation. You write both at the same time, so it’s a literate program. I’m not there. I don’t think that. I don’t know if his view is because he publishes his programs.

I don’t know if it’s a left-brain/right-brain shift, or what it is, but when you write the documentation you think about the program differently to when you write the code. So I guess writing literate programs forces that shift as you’re doing it. Which might be very productive. I did do some literate Erlang though I haven’t actually used it for a very long time. So that’s an interesting idea—perhaps I should wake it up again and write some stuff using literate Erlang. I’m not against the idea but I’m sort of impatient and wanted to write the code and not the documentation. But if you really want to understand it then I think writing the documentation is an essential step.

If I were programming Haskell, I would be forced to think about the types pretty early and document them and write them down. If you’re programming in Lisp or Erlang you can start writing the code and you haven’t really thought about the types. And in a way, writing the documentation is thinking about the types in a way. I suppose you start off with “is a”. You say, “A melody is a sequence of notes.” Right. OK. A melody is a sequence of chords where each chord is a parallel composition of notes of the same duration. Just by defining terms in your documentation—a something is a something—you’re doing a sort of type analysis and you’re thinking declaratively about what the data structures are.

Seibel:Do you think overall programming languages are getting better? Are we on a trajectory where we learn enough lessons from the past and come up with enough new ideas?

Armstrong:Yes. The new languages are good. Haskell and things like that. Erlang. Then there are some funny languages that should really be used. Prolog is a beautiful language but not widely used. It sort of peaked; Kowalski called it a solution looking for a problem.

Seibel:Dan Ingalls mentioned Prolog as an example of the kind of idea that we should really revisit now that we’ve had a couple decades of Moore’s Law.

Armstrong:Prolog is so different to all the other programming languages. It’s just this amazing way of thinking. And it’s not appropriate to all problems. But it is appropriate to an extremely large set of problems. It’s not widely used. And it’s a great shame because programs are incredibly short. I think I went into shock when I wrote my first Prolog program. It’s a kind of shocking experience. You just walk around going, where’s the program—I haven’t written a program. You just told it a few facts about the system, about your problem. Here it is figuring out what to do. It’s wonderful. I should go back to Prolog—drop Erlang.

Seibel:Are there other skills that are not directly related to programming that you feel have improved your programming or that are valuable to have as a programmer?

Armstrong:Writing is. There’s some computer scientist that said, “Oh, if you’re no good at English you’ll never be a very good programmer.”

Seibel:I think Dijkstra had something about that.

Armstrong:I’ve occasionally been asked to advise people at universities on choice of syllabus subjects for computer science courses, being as how I work for industry—what does industry want? And I say, “Well, turn ’em out being able to write and argue cogently.” Most graduates who come out, and they’ve got degrees in computer science, writing’s not their strong point.

I think it’s actually very difficult to teach because it’s very individual. Somebody’s got to take your text and a red pen and explain to you what you did wrong. And that’s very time consuming. Have you ever read Hamming’s advice to young researchers?

Seibel:“You and Your Research”?

Armstrong:He says things like, “Do good stuff.” He says, “If you don’t do good stuff, in good areas, it doesn’t matter what you do.” And Hamming said, “I always spend a day a week learning new stuff. That means I spend 20 percent more of my time than my colleagues learning new stuff. Now 20 percent at compound interest means that after four and a half years I will know twice as much as them. And because of compound interest, this 20 percent extra, one day a week, after five years I will know three times as much,” or whatever the figures are. And I think that’s very true. Because I do research I don’t spend 20 percent of my time thinking about new stuff, I spend 40 percent of my time thinking about new stuff. And I’ve done it for 30 years. So I’ve noticed that I know a lot of stuff. When I get pulled in as a troubleshooter, boom, do it that way, do it that way. You were asking earlier what should one do to become a better programmer? Spend 20 percent of your time learning stuff—because it’s compounded. Read Hamming’s paper. It’s good. Very good.

Seibel:Do you find some code beautiful?

Armstrong:Yes. Why this is I don’t know. The funny thing is, if you give two programmers the same problem—it depends on the problem, but problems of a more mathematical nature, they can often end up writing the same code. Subject to just formatting issues and relabeling the variables and the function names, it’s isomorphic—it’s exactly the same algorithms. Are we creating these things or are we just pulling the cobwebs off? It’s like a statue that’s there and we’re pulling the cobwebs off and revealing the algorithm that’s always been there. So are we inventing a new algorithm or are we inventing a structure that already exists? Some algorithms feel like that. I think it’s more the mathematical algorithms. I don’t get that feeling when I’m implementing a telephony protocol or something. That’s not a statue that I’m pulling the cobwebs off.

Seibel:So that’s similar to the beauty of math, because it’s part of nature. Then there are other levels at which code sort of has an aesthetic.

Armstrong:Yeah. It’s kind of feng shui. I like minimalistic code, very beautifully poised, structured code. If you start removing things, if you get to the point where if you were to remove anything more it would not work any more—at this point it is beautiful. Where every change that you could conceivably make, makes it a worse algorithm, at that point it becomes beautiful.