Literate Programming Solves The Wrong Problem
Literate programming is advocated by some highly regarded programmers. Even Donald Knuth. Despite this, it has failed to gain much traction in commercial or hobby projects.
what characterises literate programming?
(1) The code and documentation are written together, in an interleaved format.
(2) The compiled code is generated from this interleaved format, reordering it to suit the language required.
3 A document targeting readers is generated, usually a PDF.
isn't prose optimal for comprehension?
Code is rarely read for pleasure. Source code is consulted to understand a specific behaviour, or to change behaviour.
Prose assumes that source code will be read.
doesn't literate programming catch bugs?
Certainly! It's not clear that this is specific to literate programming though.
If you're writing a document, it's often easier to spot typos by changing the margin width or the font. That doesn't mean previous margin was wrong, simply that a new perspective can highlight issues.
what is the right problem?
Source code should be easy to navigate and edit.