alt Hacker NewsI seriously looked into it many years ago...
One problem with "literate programming" is it assumes that good coders are also good writers, and the good writers are also good coders.
Another problem is that the source files for the production code will have to be "touched" for documentation changes. Which IMHO is an absolution no-no for production code. Once the code has been validated, no more edits! If you want to edit docs, go ahead, just don't edit the actual source.
I would turn this around --- it acknowledges the fact that if one needs to write a complex program, and to maintain it over the long term, one will need not just the raw code, but also documentation for how that code was written, and how changes to it should be approached.
As I noted elsethread, the big thing which Literate Programming has netted me is that it makes editing easier/manageable, even for long and complex projects spread across multiple files --- having the single point of control/interaction where I can:
- make the actual change to the code to implement a new feature
- change the optional library which exposes this project to a secondary language
- update the documentation to note the new interface
- update the sample template files (one for the main implementation, the other for the secondary) to reflect the new feature
- update an on-going notes.txt file where the need for the new feature was originally noted
is _huge_ and ensures that no file is missed in the update.