One of my favorite examples of a literate-style program is "cl-6502, A Readable CPU Emulator" by Brit Butler
Literate programming is much more than just commenting code
91–100 of 112 posts
Re: Literate programming is much more than just commenting code
#92Earlier quoted context omitted.
Refactoring becomes the dual problem space of both programming and editing. It's simply more work - but that "more work" is vitally important, tedious, and resistant to any kind of automated help.
With Emacs org-babel I just do the refactor using the normal tools for whatever language on the tangled files and then detangle it back to the literate document. There's no problem here.
By "editing" I didn't mean editing the source. I meant the writing process, editing [0]. The thing you may hire an Editor to do. It is not something that you can automate, and the difficulty has very little to do with the tooling.
A slight change in code structure, may require many hundreds of adaptions to the literate document, for example.
[0] https://www.postgraduate.uwa.edu.au/__data/assets/pdf_file/0...
Re: Literate programming is much more than just commenting code
#93What are the key differences between a human audience and a machine interpreter? It is not the language or prose. It is the structure and order. For machines, details comes first. You declare all the actors and types with every non-forgiving annotations first. You may tuck the details into a header, but it still needs be ordered according to compilers and structured in the way that machines gets the details first. On…
Context can be expresses with thin, somewhat redundant interfaces that group code around how they map to desiderata. Eg the meat in “matrix pseudoinverse” and “linear regression” is the same, but you can expose domain-meaningful abstractions. Regular OOP does “tangle and weave” without the messy text transformation mechanics.
I guess the word "context" has been misused in computer science. An interface is a computer context. In particular, an interface is full of non-negotiating details. A human context is about why (we need it), what (we want), and how (to achieve the goal at high level). Most details at high level is understood as the ways things can go wrong. This understanding provides context when we later dive into the details.
An interface with all its details is an end product. With literate programming, that shouldn't show up as a single piece up-front. It should be developed with layers, each layer with its context (why, what, how), each layer with design and implementation.
Certainly we still want a view of complete interface with all its details in one place. This is the same as the compiler still wants the entire code in its expected structure and order. That's the job of tangle.
Re: Literate programming is much more than just commenting code
#94I think likewise. When I had to write the radix tree implementation for Redis I faced two problems: - I needed a stable implemention as soon as possible, I had a performance issued that needed to be solved by range queries. - The radix tree was full of corner cases. So I resorted to literate programming, which is in general very near to my usual programming style. You can find it in the rax.c file inside the Redis so…
For those curious, the extensively commented source code can be seen here:
Re: Literate programming is much more than just commenting code
#95I think Literate Programming is fantastic when used to teach computational thinking.
On a side note, it seems a lot of the other commenters miss one of the best "features" of LP - minimizing repetition. Chunks of code can be reused and so patterns can become clearly evident. Also, chunks can be defined "out-of-order".
Re: Literate programming is much more than just commenting code
#96The problems one will run into with literate programming: 1. Lack of tooling. 2. Refactoring becomes nontrivial 3. How one would write a program in literate style will vary widely from person to person. If you write your code in literate style, it may be easy for you to follow it years later and modify it, but it likely will not be the case for a coworker. If they have to modify the code, the cognitive load will not…
For point 3. - it's exactly the same with code that's not literate. Writing code is ultimately about expressing ideas using a language, which is really much closer to writing a novel than to drawing a plan for a bridge. As such, if you want to make your code understandable to other, you have to learn to write well. Just like with novels, there's no problem with having a personal style, or a specific flavor that comes from how you use the language, how you structure your sentences and paragraphs, how you guide a reader through the story.
In other words, the style varying between people is not a problem - bad writing is. And, unfortunately, in my experience very few programmers are capable of consciously producing good writing. The fact that most of the docs out there are barely-legible trash is a proof of this.
I'm sure that reading literate code from Charles Stross would be a blast. It would be exciting, sometimes surprising, but still clear, easy to navigate, structured in a way allowing for extension within a well thought-out framework. Unfortunately, when people without his talent try to use LP, they produce things on par with that unfinished fantasy novel you started writing in 8th grade.
Programming requires a bit of talent, but you can get by with lots of hard work. Literate programming is much harder than that and requires a lot of talent to be beneficial to the codebase. Without that, your LP code will be Fifty Shades of Twilight, and honestly, we don't need more of things like that.
Re: Literate programming is much more than just commenting code
#97The problems one will run into with literate programming: 1. Lack of tooling. 2. Refactoring becomes nontrivial 3. How one would write a program in literate style will vary widely from person to person. If you write your code in literate style, it may be easy for you to follow it years later and modify it, but it likely will not be the case for a coworker. If they have to modify the code, the cognitive load will not…
For point 3. - it's exactly the same with code that's not literate. Writing code is ultimately about expressing ideas using a language, which is really much closer to writing a novel than to drawing a plan for a bridge. As such, if you want to make your code understandable to other, you have to learn to write well. Just like with novels, there's no problem with having a personal style, or a specific flavor that comes…
It's a nice perspective, but the fact that more people have read Fifty Shades/Twilight than the sum total of all who have read any of Charles Stross's works undercuts your point.
And while you add to point 3, it wasn't my main point.
Take any two exceptionally good writers who have very different styles. If one of them produces literate code, the other may be able to understand it very well, but it is unlikely that he can modify it, along with the prose, and maintain the quality of the literate document.
It's not just about bad writers, but incompatibly good ones.
Re: Literate programming is much more than just commenting code
#98Literate programming is going to feel far more powerful when we expand the definition to include: - Smalltalk-ish things like writing suites of custom viewers for various types, - demos and examples in-line inside of a library - multiple stories about the same piece of code, but all with the ability to IMPORT the story as a library I've been writing sicmutils[0] as a "literate library"; see the automatic differentiat…
Don't forget to include "notebooks" in the expanded view of literate programming. The amount of code being written in Jupyter notebooks alone today in practice dwarves much of literate programming in preceding years.
Re: Literate programming is much more than just commenting code
#99I would go further: literate programming is not just "much more than" commenting code, because you can do LP without commenting much. The main thing in LP is the idea/orientation of writing as if you're writing something for a human reader. This does often lead to more comments, but even something like "here's the code" followed by lots of code can be LP, if you deem it sufficient for your intended audience. (Earlier…
I'm somewhat hopeful the growing ubiquity of especially Jupyter notebooks leads to better, more universal tools for literate programming. Notebooks have always been a form of literate programming. Jupyter and its underlying formats are now ubiquitous enough with a lot of strong IDE support (across a variety of IDEs) that I'm hopeful a better convergence as a "general literate programming platform" from the notebook side may just be a matter of time. (Other than that a lot of strong LP proponents so far seem to mostly be oblivious to the happenings in Notebook spaces and vice versa, despite there being so much cross-over.)
Re: Literate programming is much more than just commenting code
#100The problems one will run into with literate programming: 1. Lack of tooling. 2. Refactoring becomes nontrivial 3. How one would write a program in literate style will vary widely from person to person. If you write your code in literate style, it may be easy for you to follow it years later and modify it, but it likely will not be the case for a coworker. If they have to modify the code, the cognitive load will not…
I feel like problem 1 is on the cusp of solutions given the amount of money poured into tooling for "notebooks" like Jupyter. Notebooks are a form of literate programming. Projects written in Jupyter Notebooks are getting larger and scaling harder. I think a convergence should eventually happen that larger scale literate programming tasks can benefit immensely from the tooling investments in notebooks like Jupyter.