5. Donald Knuth on Literate Programming

The following is a transcript from an excerpt from an interview with Donald Knuth posted on YouTube on 16-Oct-2020. In this portion of the interview, Donald describes Literate Programming.

“The key idea that I realized as I’m writing The Art of Computer Programming (the textbook) [is] that the key to good exposition is to say everything twice (or 3 times) where I say something informally and formally. Then the reader gets to lodge it in his brain in 2 different ways, and they reinforce each other.

“I’m giving a definition and then immediately I apply the definition to a simple case, so that the person learns ... what it means, but also to internalize [it by] using it once in their head.

“So [in] describing a computer program, it’s natural to say everything in the program twice so that you say in English what the goals of this part of the program are, and then you say [it] in your computer language, and you alternate between the informal and the formal. And Literate Programming enforces this idea.

“It has very interesting effects because, I find that, for example, writing a system program.... I did examples with Literate Programming where I took device drivers that I received from Sun Microsystems—they had device drivers for one of my printers. And I re-wrote the device driver so that I could combine my laser printer with a previewer that would get exactly the same raster image.

“So I took this industrial-strength software and I re-did it as a Literate Program, and I found out that the Literate version was actually a lot better in several other ways that [were] completely unexpected to me because it was more robust.

“When you’re writing a subroutine in the normal way, a good system program subroutine is supposed to check [that] its parameters make sense or else it’s going to crash the machine. And if they don’t make sense, it tries to do a reasonable error recovery from the bad data.

“If you’re writing the subroutine in the ordinary way ... if you do a really good job of this testing and error recovery, it turns out that your subroutine ends up having 30 lines of code for error recovery and checking, and 5 lines of code for what the real purpose of the subroutine is. It doesn’t look right to you. You’re looking at the subroutine... it looks like the purpose of the subroutine is to write certain error messages out, or something like this.

“Since it doesn’t quite look right, a programmer, as he is writing it, is suddenly, unconsciously, encouraged to minimize the amount of error checking that’s going on, and get it done in some elegant fashion that you can see what the real purpose of the subroutine is in these 5 lines.

“Now, with Literate Programming, you start out—you write the subroutine and you put a line in there to say,

/* Check parameters for errors. */

and then you do your 5 lines [and conclude that the] subroutine looks good. Now you turn the page. On the next page it says, ‘Check parameters for errors’. Now you’re encouraged as you’re writing the next page, it looks really right to do a good [job of] checking for errors. And this kind of thing happened over and over again when I was looking at the industrial software. So this is probably what I meant by some of the effects of it. But the main point of being able to combine the informal [English] and the formal [code] means that ... a human being can understand the code much better than just looking at one or the other, or just looking at an ordinary program with sprinkled comments.

“It’s so much easier to maintain the program, and in the comments you also explain what doesn’t work, or any subtleties where you could say,

‘Note the following: the tricky part in line 5 ... and it works because __________.’

“You can explain all of the things a maintainer needs to know.

“I’m a maintainer too, but after a year, I’ve forgotten totally what I was thinking when I wrote the program.

“So all this goes in as part of the Literate Program. [It] makes the program easier to debug, easier to maintain, and better in quality—it does better error messages and things like that, because of the other effects. That’s why I am so convinced that Literate Programming is a great spin-off of the Tex Project.”

Another (rough) quote from another interview mentioning Literate Programming:

“When you are writing source code, you are not just teaching the computer what to do, but also teaching other programmers how it works, not only users of the API, but also future maintainers of your source code. Comments add information about what the author was thinking when the code was written, and why you did things that way—subtleties about the design that cannot be conveyed by the source code alone.”