Live data from Hacker News

What is “literate programming”? (2024)

pqnelson.github.io

21–30 of 57 posts

Re: What is “literate programming”? (2024)

#21

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

That’s true, I was mostly referring to it in a professional setting, not for educational purposes.

Re: What is “literate programming”? (2024)

#22
post #8

Maybe 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…

search for "Controlled natural language". Many attempts in the past - ~20y ago, one of these is even called "Attempto", near nothing recently. Seems not enough interest in wide audiences

Re: What is “literate programming”? (2024)

#23
An 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 segments. This allows using a normal programming environment (not possible in first approach) and being order independent (not possible in second approach).

[0]: https://github.com/eudoxia0/airloom

Re: What is “literate programming”? (2024)

#25
I seriously looked into it many years ago...

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.

Re: What is “literate programming”? (2024)

#26
post #19
post #16

Earlier 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…

There is Org Babel in Emacs that can be an alternative to jupyter notebooks for literate programming (research/devopsy tasks). It is more powerful in some aspects and weaker in others.

Re: What is “literate programming”? (2024)

#27
relatedly, i have been using literate haskell to document my advent of code journey this year:

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

#28

An 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…

There is also verso / recto that uses the same technique.

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)

#30

An 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…

Thanks for mentioning this. I built the same thing a year ago for myself in dozen lines of AWK. Looks like great minds think alike :)

In my opinion this is the most practical approach for real world projects. You get benefits like avoiding outdated documentation without huge upfront costs.

Post reply on HN