Literate programming tool for any language
23 comments
·June 19, 2025jostylr
I've been wondering if AI coding agent world makes literate programming valuable again. I got into it with JavaScript being a mess prior to the modern changes. Needed a lot of workarounds. Then they improved the language and it felt like coding could be efficient with them. But if the programmer switched from coding to reviewing, maybe it would be good to be able to have various snippets, with an explanation preceding it and then verifying it. Haven't tried it yet. But I do wonder.
seanwilson
Maybe I'm missing something but how often is the English in literate programming repeating what's already written in the code? Does it work for large projects where it's often hard to explain all the parts in a linear way in the style of an essay?
I avoid code comments where I can because English is way less precise than code, it's an extra chore to keep the comments and code in sync, and when the comments and code inevitably get out of sync it's confusing which one is the source of truth. Does literate programming sidestep this somehow? Or have benefits that outweigh this?
taeric
I think this certainly happens a fair bit. Not at all uncommon to have a section that largely says what is going to happen next, which, fair that what is going to happen is what happens.
I think where it shines, is where it helps you break the code up, without having to break it up in a way that makes sense for the computer. Show an outline, but then drill into a section. The overall function can then be kept as a single unit, and you can sort of punt on sub sections. I tried this just recently in https://taeric.github.io/many_sums.html. I don't know that I succeeded, necessarily. Indeed, I think I probably should have broken things into more sections. That said, I did find that this helped me write the code more than I expected it to. (I also was very surprised at how effective the goto style of thinking was... Much to my chagrin.)
I will have to look again at some of the code I've read this way.
To directly answer the question of if it helped keep the documentation in sync, as it were, that is tough. I think it helps keep the code in a section directly related to the documentation for that section. All too often, the majority of code around something is not related to what you were wanting to do. Even the general use of common code constructs gets in the way of reading what you were doing. Literate programming seems the best way I have seen to give the narrative the ability to say "here is the outline necessary for a function" and then "this particular code is to do ..." Obviously, though, it is no panacea.
juliangmp
I'm not sure who first coined this idea or put it in a book or where I've read it, but for code comments I generally like the "explain why, not what" philosophy. The "what" is answered by the code itself and should be easy enough to comprehend if your design is simple and your names meaningful. The "why" is much more important. Why does this parser check for some magic numbers at this specific offset and change some parameters if it finds them? If you don't explain that its because of e.g. compatibility with some legacy format, its gonna be a mystery to the reader.
w10-1
This doesn't seem to provide any context for literate programming, or the core literate operations?
cf leo editor for literate programming in python [0]
Yes, markdown has code blocks, and notebooks have embedded code in documentation since Mathematica in the 1980's. It is possible to get IDE support in such blocks.
But for literate programming, weaving/tangling sources is needed to escape the file structure, particularly when the build system imposes its own logic, and sometimes one needs to navigate into the code. Leo shows how complicated the semantics of weaving can get.
Eclipse as an IDE was great because their editor component made it easy to manage the trick of one editor for many sources, and their markers provided landmarks for cross-source navigation and summaries.
svieira
The fact that the actual implementation is in `lit` too is really helpful - getting to see how one would actually use this on a larger program does make it much more intriguing than the simple examples (and much more approachable than TeX itself).
amanwithnoplan
Another interesting implementation of literate programming with _bidirectional sync_ between documentation and source code is Entangled (https://entangled.github.io/). This allows you to use all your normal tooling on the normal source code files, and the changes are reflected back to your Markdown documentation files.
mapcars
Literate programming is an intriguing concept, but its hard to compete with modern IDEs. Having build system is good, but can you get proper syntax highlight for the code segments? Or goto-symbol, real-time typechecking?
I feel like it needs its own IDE, because now apart from the coding abstractions you also have named snippets.
null
corysama
Code-as-a-Database is something lots of people would like to have, but not much effort has been put into implementation since... Smalltalk? Could still be a pile of loose text files with markup. Like how https://obsidian.md/ is an informal graph database of loose markdown files.
ModernMech
There's an active research community based around this very idea: https://liveprog.org, also https://www.hytradboi.com
nico
Great concept and very relevant today[1]
It’s interesting that using LLMs is making very explicit that “someone” needs to read the code and understand it. So having good comments and making code readable is great both for AI and humans
1: “Writing documentation for AI: best practices” https://news.ycombinator.com/item?id=44311217
tony_cannistra
Been around for a long time indeed. I first learned literate programming in college at Tufts, from Norman Ramsey. He wrote noweb[1], an early implementation of Knuth's ideas.
onair4you
Oh you beat me to it!
thyrsus
If your colleagues just don't feel the benefit of the extra .lit file, is there a way to pull their changes to the derived files into your own .lit files and to keep the .lit files in a parallel version control repo or branch?
JAHDIEL1
Español
I actually did some small hobby projects using Literate Coffeescript back in the day. Looking at the source code today, and I can't help but feel like the proponents of literate programming were really onto something. I'm coming back years later, but I can easily see what's going on and why at a glance. Compared to many other projects that I've written in the past without documentation, it's a completely different vibe.
Yeah, it can look a bit repetitive if the code is already clear, but the contextul why of the things being done is still valuable. In the modern era with LLM tools, I'm sure it could be even more powerful.