What is “literate programming”? (2024)

Couple things that helped me understand literate programming:

- A literate program has code and documentation interleaved in one file.

- Weaving means extracting documentation and turning it into e.g. a pdf.

- Tangling means extracting code in a form that is understandable to a compiler.

A crucial thing to actually make this paradigm useful is the ability to change around the order of your code snippets, i.e. not letting the compiler dictate order. This enables you to code top-down/bottom-up how ever you see fit, like the article mentioned. My guess on why people soured on literate programming is that their first introduction involved using tools that didn't have this ability (e.g. jupyter notebooks). Also, you usually lose a lot of IDE features: no go-to-definition, bad auto-complete, etc.

IMO, the best tool that qualifies for proper literate programming is probably org-mode with org-babel. It's programming language agnostic, supports syntax highlighting and noWEB for changing around order. Of course it requires getting into the Emacs ecosystem, so it's destined to stay obscure.

I’d guess that tools like Doxygen and Apple docc are probably the most obvious examples of documentation extraction.

I’ve written code for many years, with Doxygen/Jazzy/docc in mind (still do[0]). I feel that it’s a big help.

[0] https://littlegreenviper.com/leaving-a-legacy/

Documentation like doxygens is almost completely opposite from literate programming. The comment you are responding to emphasizes the ability to determine yourself the order in which to present the documentation. Literate programming is writing a document in the first place where, as an afterthought, a program can be extracted. Source code with doxygen is source code where, as an afterthought, documention can be extracted from. In many cases doxygen documention is quite worthless. Very often it is very helpfully documented that the method get_height, "gets the height". It is very fragmentary documentation where the big picture is completely missing. There is also a case where doxygen-like documentation is needed. This is when writing a library that is going to be used by many people. But then the doxygen comments should only be used on methods that you want those other people to use. And then there is still the danger that there will be too little higher level documentation because the doxygen is treated like it is sufficient.

Literate programming is, in my opinion, only used very seldomly because keeping an accurate big picture view of a program up to date is a lot of work. It fits with a waterfall development process where everything that the program is supposed to do is known beforehand. It fits well with education. I think it is no coincidence that it was brought to prominence by D.E. Knuth who is also very famous as an educator.