(2014-10-30) Agaram Literate Programming Knuth Is Doing It Wrong

Kartik Agaram says Literate programming: Donald Knuth is doing it wrong. On the whole, people have failed to appreciate the promise of literate programming because the early examples are just not that good, barring the small program in Knuth's original paper.

these early examples are fine for what they are. They haven't developed because we programmers have failed to develop them over time.

There's a fundamental problem with generating a beautifully typeset document for a codebase: it's dead. It can't render inside just about any actual programming environment (editor or IDE) on this planet, and so we can't make changes to it while we work on the codebase.

What's the alternative? In the spirit of presenting a target of my own for others to attack, I'll point you at some literate code I wrote last year for a simple interpreter. A sample of what it looks like:

A previous post describes the format, but we won't need more details for this example. Just note that it is simple plaintext that will open up in your text editor. There is minimal prose, because just the order of presentation does so much heavy lifting

Here's a test harness. (With, I can't resist pointing out, the includes at the bottom.)

Eventually I'd like to live in a world where our systems for viewing live, modifiable, interactive code (REPL) are as adept at typesetting as our publishing systems are. But until that day, I'll choose simple markdown-like plain-text documentation that the author labored over the structure of. Every single time.