Literate Programming — Explained with Examples

Literate programming is a programming paradigm introduced by Donald Knuth in 1984 that treats a program as a piece of literature intended for human readers, rather than primarily as instructions for a computer. In literate programming, explanatory text is the primary artifact, and code is woven into the narrative.

Knuth’s WEB system (later CWEB for C) allowed programmers to write code in any order that makes sense for human comprehension — not the order required by the compiler. A tangle process extracts machine-executable code, and a weave process produces formatted documentation. Modern literate programming tools include Jupyter Notebooks, R Markdown, Quarto, and Org-mode with Babel. While not widely adopted for production software, literate programming principles influence documentation-driven development and executable documentation.

Real-world analogy. Literate programming is like a cookbook that includes the chef’s stories, explanations, and tips alongside each recipe. The story (prose) is the main feature — the ingredient list and steps (code) work perfectly but are presented within the narrative context. You learn why the dish works, not just how to make it.

Example (WEB-style literate pseudocode):

@ The factorial function uses recursion. For any positive integer n,
the factorial is n × (n-1) × ... × 1. Here is the implementation:

@p function factorial(n: integer): integer;
begin
    if n <= 1 then
        factorial := 1
    else
        factorial := n * factorial(n - 1)
end;

Related terms: Documentation, Clean Code, Test-Driven Development, Declarative vs Imperative, Technical Debt