A Literate Programming Experiment Part 1: An Attractive Idea

2026-10-03

I want to try out literate programming. Specifically, I want to test if the process is truly effective. This is a little daunting because to me, literate programming is an attractive idea.

Attractive Ideas

Attractive ideas are difficult to reject because, if true, they would solve a very real problem. In the 1980's, Martin Fleishman and Stanley Pons announced they found a way to produce nuclear energy at room temperature using a tabletop setup. The press blitz termed the phenomenon "cold fusion", and it seemed like it could solve humanity's dependency on fossil fuels.

If we expect our descendants to live virtually indefinitely on this planet—until perhaps our Sun, our fusion reactor in the sky, "dies" some five billion years hence—we had better plan now to possess a source of inexhaustible power. --- Eugene F. Mallove

(see Mallove, Eugene F., 1991 p. 4)

Cold fusion is an attractive idea. Eugene Mallove published a glowing book on the subject. Unfortunately it's bullshit.

The first principle is that you must not fool yourself --- and you are the easiest person to fool.

(see Feynman, Richard P. & Leighton, Ralph, 1985 p. 385)

A corollary to the Richard Feynman sound byte: the best way to lie to somebody is to tell them what they want to hear --- and that person can be yourself.

Literate Programming

In the 1980's Donald Knuth shared his working method, an inversion of the relationship between source code and comments. The source document is an all-in-one markup file which is "tangled" into compilable or executable source code, and "woven" into a formatted document.

It's an attractive idea. Literate programming would solve the problem of poor or insufficient documentation by putting documentation first. Literate programming would produce better code by forcing the programmer to prove they know what they're executing by explaining it. Literate programming would allow programmers to emulate the "Yoda of Silicon Valley".

Bullshit ?

But is literate programming bullshit? The benefits are anecdotal; Knuth's 1984 argument for adoption boils down to "it works for me". Outside of notebook interfaces like Jupyter, literate programming hasn't seen mass adoption.

Like cold fusion re-enters the chat from time to time , so does literate programming. In 2013 Timothy Daly, the maintainer of scientific computing software axiom, advocated that organizations maintain their entire codebases as literate programming documents. The axiom source code itself is built in a "literate programming style". More recently, Howard Abrams demoing his own process using emacs' org-mode to program "for the 24th 1/2 Century", with a focus on DevOps work. They sound appealing, but offer about as much proof for or against the process as some polo shirt bro offers when pushing Ralph Loops as the magic A.I. bullet for the future. Don't buy in on something just because it's what you want to hear.

The Experiment

This series of posts is about an informal experiment.

I want to test the merits of the attractive idea and do so without fooling myself. To do that, the venture needs to be falsifiable.

Does literate programming, in fact, work? Does Literate Programming yield the expected benefits (comprehension, documentation, code quality)? Is Literate Programming possible in a language-agnostic environment like emacs' org-mode? Can Literate Programming be broken by a space-sensitive language like Python? Does Literate Programming yield benefits worth the additional time?

In order to stress-test the above questions, I'll recreate Knuth's 1984 prime numbers example and workflow with modern tools. For rigor and replicatability. I'll log my process here, because even a qualitative value needs some means of measurement.

Next Up: Constraints, Ground Rules and Metrics

References

Feynman, Richard P. & Leighton, Ralph (1985). "Surely you're joking, Mr. Feynman!": Adventures of a Curious Character, W.W. Norton & Company, Inc..

Mallove, Eugene F. (1991). Fire from Ice: searching for the truth behind the cold fusion furor, John Wiley & Sons, Inc.