Literate Programming

Don Knuth coined the term "Literate Programming" to describing a method of exposition coupled to writing computer software. It was both literature and software. Unfortunately, since Javadoc, everyone has co-opted the term to refer to inline documentation of software, or something along those lines.

Knuth's idea works well for static projects, or for writing code which non-programmer experts review. The latter case takes advantage of the "Web style" the documentation affords, so a non-programmer can read it as if it were pseudocode.

But it doesn't adequately work with agile methods. I'm not even clear how to unit test code in this manner. If I had to iteratively refine some code, I wouldn't know how to do that effectively. There have been times when I wanted to create a stub, then revise it later (so the chapter could form a self-contained program). Literate programming doesn't handle the "then revise it later" step. Presumably I could have used function pointers to abstract away the methods used, or some other fancy trick.

The original software Knuth used for literate programming which allowed the author to extract Pascal code, which was then compiled into a binary for execution. This is how Knuth wrote TeX, which was then used to write Web (to make the documentation pretty).

A web program consists of "chunks". Each chunk was numbered, and had some optional English text, followed by an optional source code fragment, but must have at least one of either. (Empty chunks were not allowed.) The code snippet could refer to other chunks as a sort of pseudocode, writing something like <Sort applicants by height> then later implement the code in a chunk named "Sort applicants by height".

But Pascal didn't have the longevity of C. Thus begat CWeb. It had the same style of chunks, labels, etc., but used C code instead of Pascal.

Following Knuth's enthusiastic examples, Javadoc added documentation for Java code using comments. (Lisp had this earlier in comment strings, but Javadoc extracted documentation from specific comments.) Since then, the programming community had misinterpreted "literate programming" as "programming with API documentation embedded as comments".

Jupyter (formerly Python Notebooks) tried to introduce something closer to Knuth's sense of literate programming, but it didn't really adhere to Knuth's intentions. Org-babel seems to work along similar lines as Jupyter.

For the most part, it's fine. After having acquired a taste for unit testing, it's a little unnatural at first (since C doesn't have a unit testing framework). My exposition has been at the level of documenting design decision, discussing alternatives, and so on. I suspect this is not quite what Knuth had in mind.

The best example of a literate program, to my mind, is Bob Nystrom's Crafting Interpreters. He wrote his own toolkit to splice into his book (written in markdown) segments of code from a C program (or Java program). This probably tells a lot about the approach taken to writing a literate program, that the best one wrote the code first (albeit with explanations in mind) and worked a book around the code.

I dislike org-mode's literate programming features, since it doesn't mesh well with org-mode. There's no way to create "chunks" the same way I could in cweb. On the other hand, each chunk is really six or seven stars, and I get to cluster them together in a way that is natural for org-mode.

I've been tinkering with Noweb to write a literate program in C, ACSL, and Twelf. I think this may be a promising approach when working with multiple languages.

Briefly commands:

• Noweb files have a .nw suffix
• Extract HTML: noweave -filter l2h -index -html foo.nw > foo.html
• Extract TeX file: noweave -x foo.nw > foo.tex
• Extract code: notangle -L -Rfoo.c foo.nw > foo.c

Formatting:

• @ as the first character starts a documentation chunk
• In LaTeX, [[ ... ]] for embedded code fragments
• Use noweave -delay to avoid automatically wrapping a document class, begin/end document environment
• Start a code chunk with <<name of chunk>>=
• Insert a code chunk by reference with <<...>>
• Chunk naming conventions:
  • Name chunks inside functions with verbs, usually in imperative mood ("Do this", "Sort that", etc.)
  • Name chunks holding declaration prototypes with nouns (e.g., "private function prototypes", "definitions of exported functions", etc.)
  • Name top-level "root" chunks after the files they are to represent (e.g., <<foo.c>>= or <<foo.h>>=)

There are a few passages worth quoting from Knuth's article on structured programming with the goto statement. In the discussion after example 5a:

If such automatic goto elimination procedures are applied to badly structured programs, we can expect the resulting programs to be at least as badly structured. Dijkstra pointed this out already in 1968 [21], saying:

    The exercise to translate an arbitrary flow diagram more or less 
    mechanically into a jumpless one, however, is not to be recommended.
    Then the resulting flow diagram cannot be expected to be more
    transparent than the original one.

In other words, we shouldn't merely remove goto statements because it's the fashionable thing to do; the presence or absence of goto statements is not really the issue. The underlying structure of the program is what counts, and we want only to avoid usages that somehow clutter up the program. Good structure can be expressed in FORTRAN or COBOL, or even in assembly language, although less clearly and with much more trouble. The real goal is to formulate our programs in such a way that they are easily understood.

Program structure refers to the way in which a complex algorithm is built up from successively simpler processes. In most situations this structure can be described very nicely in terms of sequential compositions, conditionals, and simple iterations, together with case statements for multiway branches. Undisciplined goto statements make program structure harder to perceive, and they are often symptoms of a poor conceptual formulation. But there has been far too much emphasis on goto elimination instead of on the really important issues; people have a natural tendency to set up an easily understood quantitative goal like the abolition of jumps, instead of working directly for a qualitative goal like good program structure. In a similar way, many people have set up "zero population growth" as a goal to be achieved, when they really desire living conditions that are much harder to quantify.

Probably the worst mistake any one can make with respect to the subject of go to statements is to assume that "structured programming" is achieved by writing programs as we always have and then eliminating the goto's. Most goto's shouldn't be there in the first place! What we really want is to conceive of our program in such a way that we rarely even think about goto statements, because the real need for them hardly ever arises. The language in which we express our ideas has a strong influence on our thought processes. Therefore, Dijkstra [21] asks for more new language features—structures that encourage clear thinking—in order to avoid the goto's temptations toward complications.

Emphasis in bold is mine.

• Donald Knuth, Literate Programming. CSLI Lecture Notes no 27, 1992.
• Donald Knuth, TeX: The Program. Specifically the forward on "Reading a Web".
• John Cook, Literate programming: presenting code in human order, 6 July 2016 blogpost.
• Elliot Soloway,
  "Learning to program = learning to construct mechanisms and explanations".
  Communications of ACM 29, no.9 (1986) 850–858 doi:10.1145/6592.6594.