I imagine the biggest hurdle on the path towards adopting this is writing down clear, readable prose using highly technical language. And naming things. Using ambiguous human language to describe a complex algorithm without causing a conflict in a big team.
https://www.cs.tufts.edu/~nr/cs257/archive/literate-programm...
https://www-cs-faculty.stanford.edu/~knuth/lp.html
Knuths intention seems clear enough in his own writing:
Literate programming is a methodology that combines a programming language with a documentation language, thereby making programs more robust, more portable, more easily maintained, and arguably more fun to write than programs that are written only in a high-level language. The main idea is to treat a program as a piece of literature, addressed to human beings rather than to a computer.
and
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
I find it weird to not be able to find linux source code and commentaries or even math/physics/science masterpieces in libraries where you can find Finnegan's Wake easily (at least where do I live), and not be able to talk about the GHC in between two discussion about romance or the weather at the bakery.
That one statement is a great concise explanation/motivation for "literate programming".
Explanations with code, that explain code design choices, in a way that enables the code to be understood better, and the ideas involved to be picked up and applied flexibly to reading and writing other code.
Another way to view it is: Developers are "compilers" from ideas to source. Documenting the ideas along with the "generated" source, is being "open source" about the origin and specific implementation of the source.
Heh.
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)
- 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’ve written code for many years, with Doxygen/Jazzy/docc in mind (still do[0]). I feel that it’s a big help.
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.
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.
>> - 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.
However, I don't know what this metalanguage should be. I don't know how to translate typical comments (or a literate program) into some sort of formal language. I think we have a gap in philosophy (epistemology).
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..
However, the final effect is spaghetti code (you can surrogate “goto” by injecting code in different locations.) And docs are hard to read.
But, it really forces you to explain what you do and how you got there, which is incredibly useful for reconstructing history. (Theirs is also a sort of diff file for it, I think with .ch extension, to amend files.)
https://github.com/nickpascucci/verso
I actually wish for a tool that would use two things: 1) navigate code like a file system: Class/function/lines [3..5]
2)allow us to use git commit revisions so that we could comment on the evolution of the code
So far the only thing capable has been leoEditor + org-babel
In my opinion this is the most practical approach for real world projects. You get benefits like avoiding outdated documentation without huge upfront costs.
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.
- day 5's solution for example: https://aoc.oppi.li/2.3-day-5.html#day-5
- literate haskell source: https://tangled.org/oppi.li/aoc/blob/main/src/2025/05.lhs
the book/site is "weaved" with pandoc, the code is "tangled" with a custom markdown "unlit" program that is passed to GHC.
stingraycharles•7h ago
As with most things, don’t be dogmatic.
toolslive•4h ago
It depends. If you want to learn faster, you should be dogmatic: "In der Beschränkung zeigt sich erst der Meister." If you want to become a better programmer, please do set extra challenges (fe pure lazy functional progamming only, pure literate programming, ...)
stingraycharles•3h ago