To me the definition of literate programming is much less interesting than the spirit: for complicated logic / parts of code, I try to take the reader through the whole top-down plan / approach, as if it’s a story I’m writing to my colleagues about what’s going on and why. In those parts of code I can easily have 10 times as much lines of comments than code, but it’s important to use it sparingly: people tend to star…
> As with most things, don’t be dogmatic. 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, ...)
What is “literate programming”? (2024)
21–30 of 57 posts
Re: What is “literate programming”? (2024)
#22Maybe I am weird, but I would like to see/program in a formal, yet fuzzy/modal language, which could serve as a metalanguage that describes (documents) the program. This metalanguage must have some kind of constructs to describe unknown things, or things that are deliberately simplified in favor of exposition. So basically eschew natural language completely in favor of fully formalized description, that could be mani…
Re: What is “literate programming”? (2024)
#23Re: What is “literate programming”? (2024)
#24Re: What is “literate programming”? (2024)
#25One 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.
Re: What is “literate programming”? (2024)
#26Earlier quoted context omitted.
In a way this is what notebooks are for Python and other languages. They mix documentation and code such that you can run that code and inspect the output. See for example the pytorch tutorials.
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 bet…
Re: What is “literate programming”? (2024)
#27- 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.
Re: What is “literate programming”? (2024)
#28An interesting project I stumbled upon recently is AirLoom[0], essentially a reverse literate programming tool. Rather having code and prose interweaved (either Knuth-style code-within-prose or doc-style/as-comments prose-within-code), you've them split in dedicated in segment-annotated code and prose referencing those segments. AirLoom can then produce a combined document with references replaced by the actual code…
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
Re: What is “literate programming”? (2024)
#29Re: What is “literate programming”? (2024)
#30An interesting project I stumbled upon recently is AirLoom[0], essentially a reverse literate programming tool. Rather having code and prose interweaved (either Knuth-style code-within-prose or doc-style/as-comments prose-within-code), you've them split in dedicated in segment-annotated code and prose referencing those segments. AirLoom can then produce a combined document with references replaced by the actual code…
In my opinion this is the most practical approach for real world projects. You get benefits like avoiding outdated documentation without huge upfront costs.