# Literate Programming
Literate programming is a programming paradigm introduced by [[Donald Knuth]] in 1984 that treats programs as literature meant to be read by humans. Instead of writing code with occasional comments, literate programming inverts the relationship: you write a narrative explanation of your program with code woven in. The source document is "tangled" to extract executable code and "woven" to produce human-readable documentation. Knuth developed the WEB system for Pascal and CWEB for C to implement this paradigm, and used it to write TeX and METAFONT.
The core insight is that programs should be written for human comprehension first, machine execution second. Code is presented in the order that makes narrative sense, not the order compilers require. This approach produces better documentation, encourages deeper thinking about program design, and creates documents that explain *why*, not just *what*. Modern descendants include [[Org-mode]] with Babel, Jupyter notebooks, R Markdown, and Quarto. While pure literate programming remains niche, its influence is seen in documentation tools, notebook computing, and the emphasis on readable code.
## The Literate Programming Process
```
┌─────────────────────────────────────────────────────────────┐
│ LITERATE PROGRAMMING WORKFLOW │
│ (Donald Knuth) │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ │
│ │ Literate Source │ │
│ │ (.web, .org, .Rmd) │ │
│ │ │ │
│ │ Prose + Code │ │
│ │ interwoven │ │
│ └──────────┬──────────┘ │
│ │ │
│ ┌────────────┴────────────┐ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ TANGLE │ │ WEAVE │ │
│ │ Extract │ │ Generate │ │
│ │ code │ │ docs │ │
│ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Executable │ │ Beautiful │ │
│ │ Source Code │ │ Document │ │
│ │ (.c, .py) │ │ (PDF, HTML) │ │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
## Core Principles
| Principle | Description |
|-----------|-------------|
| **Human-first** | Write for readers, not compilers |
| **Narrative order** | Present code in logical explanation order |
| **Integrated docs** | Documentation and code in one source |
| **Why, not just what** | Explain reasoning, not just mechanics |
| **Named chunks** | Code fragments have meaningful names |
## Key Concepts
| Concept | Description |
|---------|-------------|
| **Web** | The literate source document |
| **Tangle** | Extract executable code from web |
| **Weave** | Generate formatted documentation |
| **Chunk** | Named fragment of code |
| **Noweb** | Language-agnostic literate tool |
## Modern Implementations
| Tool | Language | Notes |
|------|----------|-------|
| **Jupyter** | Python, R, Julia | Interactive notebooks |
| **R Markdown** | R, Python | Statistical computing |
| **Quarto** | Multi-language | Pandoc-based publishing |
| **[[Org-mode]] Babel** | Any | Emacs, most powerful |
| **Docco** | JavaScript | Side-by-side docs |
| **Noweb** | Any | Knuth's simplified WEB |
## Traditional vs Literate
| Aspect | Traditional | Literate |
|--------|-------------|----------|
| **Primary audience** | Compiler | Human reader |
| **Order** | Compiler-required | Narrative logic |
| **Documentation** | Separate, often stale | Integrated, always current |
| **Code presentation** | Complete files | Named chunks |
| **Reading experience** | Jump around | Linear narrative |
## Benefits and Criticisms
| Aspect | Description |
|--------|-------------|
| **Better design** | Explaining forces clear thinking |
| **Living docs** | Documentation never out of sync |
| **Onboarding** | New developers can read the story |
| **Overhead** | More effort than plain code |
| **IDE support** | Historically limited |
## References
- Knuth, D. (1984). "Literate Programming"
- Knuth, D. (1992). *Literate Programming* (book)
- https://en.wikipedia.org/wiki/Literate_programming
## Related
- [[Donald Knuth]]
- [[Org-mode]]
- [[Plain Text]]
- [[Markdown]]
- [[Documentation]]
- [[Software Development]]