Literate Programming
Literate programming is a programming paradigm introduced by Donald Knuth. Literate programs interleave natural language explanations with source code. Literate programming tools then allow the extraction of documentation (weaving) and code (tangling) from the written source file.
Tools include noWEB, org-mode (using org-babel), and Jupyter Notebooks.
Approaches
Write code and documentation in one file, weave doc and tangle code from it.
- Original approach by Donald Knuth
- ✅ Order can be arbitrary
- ❌ IDE support lost
Write documentation within code as block comments, then strip the comment markers and turn everything that's not a comment into a code block.
- Examples: Basic "Reverse" Literate Programming in Emacs
- ✅ IDE support retained
- ❌ Order is dictated by compiler
Write code with named chunks. Documentation includes those chunks. A processing weaves the code into the documentation. Code and doc are separated.
- Examples: Air Loom
- ✅ IDE support retained
- ❌ …