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.
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 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)
I dream of a world where the Knuth idea of programming and mathematics are naturally embedded in our cultures, like novels are.
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.
> I find it weird to not be able to find linux source code and commentaries
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.
Couple things that helped me understand literate programming:
- 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.
>> 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.
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.
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).
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.
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 start to ignore comments if they’re low value. But it’s much more effective to have good comments than external documentation, as external documentation has a tendency to go out sync with the code.
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, ...)
"Write code top-down"[1] is to literate programming what "concentrate on writing readable code" is to code comments.
(Having said that, I firmly hold the opinion that we should all be writing READMEs in HTML[2][3] (instead of Markdown) and more fully exploring/exploiting the capabilities—and ubiquity—of web browsers to enable "smart documentation": self-contained (i.e. single-file) study aids, visualization widgets, etc[4].)
There is a substantial literate program not mentioned in the article: Inform 7. (a natural language, interactive fiction programming language)
https://github.com/ganelson/inform
From the README
"Inform is itself a literate program (written with inweb), one of the largest in the world. This means that a human-readable form of the code is continuously maintained alongside it: see Inform: The Program"
Readit News
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.
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)
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.
Deleted Comment
- 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.
>> - 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.
I’ve written code for many years, with Doxygen/Jazzy/docc in mind (still do[0]). I feel that it’s a big help.
[0] https://littlegreenviper.com/leaving-a-legacy/
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.
[0]: https://github.com/eudoxia0/airloom
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.
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, ...)
(Having said that, I firmly hold the opinion that we should all be writing READMEs in HTML[2][3] (instead of Markdown) and more fully exploring/exploiting the capabilities—and ubiquity—of web browsers to enable "smart documentation": self-contained (i.e. single-file) study aids, visualization widgets, etc[4].)
1. <https://www.teamten.com/lawrence/programming/write-code-top-...>
2. <https://hn.algolia.com/?dateRange=all&type=comment&prefix=tr...>
3. <https://crussell.ichi.city/pager.app.htm>
4. <https://holzer.online/articles/easteregg-lp-style/>
https://leo-editor.github.io/leo-editor/
https://kaleguy.github.io/leovue/#/t/2
https://ganelson.github.io/inweb/inweb/index.html
Inform 7 is arguably one of the largest programs ever written in literate style.
From the README "Inform is itself a literate program (written with inweb), one of the largest in the world. This means that a human-readable form of the code is continuously maintained alongside it: see Inform: The Program"