What is “literate programming”? (2024)

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.

OK. Fair enough, but remember that Doxygen also analyzes code structure, and can generate things like UML diagrams, and inheritance trees.

Maybe a tool like Rational Rose is more along those lines.

I’ve always been a proponent of writing code in a manner that affords analysis, later. That’s usually more than just adding headerdoc.

well, maybe it is everything that is not "illiterate programming", i.e. "programming-without-understanding".. which decade by decade gets more and more abundant/dominating.

i do similar thing which i call live-sketching.. a mostly-no-content python namespace-hierarchy of module(s) and classes (used as just namespace holders), and then add (would-do-somehing) "terminal" methods, and combine-those-into-flows actual "procedures" methods , here and there .. until the "communication" diagram starts appear out of it, and week after week, fill the missing parts. It feels like some way of writing executable spec over imagined/fake stuff, and slowly replacing the fakes with reals. Some parts never get filled. Others are replaced with big-external-pieces - as-long-as matching the spec needed. What's left is written by hand.. and all this maybe multiple cycles.

This approach allows for both keeping the knowledge of what the system should do - on the spec / hierarchical level - and freedom to leave things undone, plug some external monster, or do-it-yourself as one sees fit. The downside is that the plumbing between pieces might be bigger/messier than the pieces - if you have ever seen the spiderweb of wires above a breadboard with TTL ICs..

e.g. for my Last project - re-engineering a multiple-aging-variants of kiosk-system into coherent single codebase that can spawn each/most of the previous - took me 6 months to turn a zoo of 20x 25KLoc into single 20Kloc +- 5 for the specializations - and the code-structure still preserves the initial split-of-concerns (some call it architecture), and comms "diagram", who talks to who when/why.

But yeah, it's not for faint-hearted, and there little visibility of the amount of work going/done, as the structure at day 1 is more or less the structure at day 181, and management may decide to see only that..

>> 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.

Interesting. i have made a few times DomainSpecific-"languages" - like for chips-module-testing , or for HR-payroll stuff - expressed in some general language with an engine underneath, which allowed for both turning/rendering the DS-"code" into various machine-readable outputs - verilog, labview, .. - as well as various documentation formats. Essentially a self-contained code-piece-with-execution/s-and-documentation/s, with the feature to "explain" what goes on, change-by-change.

Never knew it might be called literate programming.

Yes, notebooks are a restrictive type of litterate programming, interactive and browser bound.

TeX was "proven" as a text/typography tool by the fact that the source code written in WEB (interleaving pascal and TeX (this is meta (metacircular))) allows for you to "render" the program as a typographed work explaining how TeX is made+ run the program as a mean to create typographic work.

I'm lacking the words for a better explanation of how do I feel sbout the distinction, but in a sense I would say that notebooks are litterate scrips, while TeX is a litterate program ? (The difference is aesthetical)