Oh you beat me to it!

There's a pretty direct line between the concept of notebooks and literate programming.

Is there any intrinsic reason why Jupyter Notebooks can't be imported? You don't know which code blocks to run?

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.

I write a bit of literate Haskell, sometimes. It's one of the most well supported literate programming systems out there: the compiler supports it, the language server supports it, using VSCode as an "IDE" means full support for all the things you mentioned. Haskell code formatters don't seem to support literate Haskell, though, and GitHub Copilot, at least, gets confused between prose and code (but that's fine, if I'm taking the time to make my code extra readable and understandable the last thing I want is for an AI to get involved).

Maybe a tool like the one presented here could work as a language server proxy to the underlying language's server. The presence of literate text alone doesn't seem to be the main issue, it's getting the code portions parsed, checked, and annotated with references that matters.

I mean... somewhat yes to all of those? Emacs can even do most of what you are asking for. When I export an org buffer, it even has the syntax highlighting in the html that I was looking at. :D

Obviously, the type checking will be a bit more limited for code snippets you haven't finished. But especially for image based environments, it should have everything that you have in the image just fine.

CWEB, which is the one that Knuth prefers, even supports step debugging. Has supported it for decades, at this point.

This is why I use LuaLaTeX for this:

https://github.com/WillAdams/gcodepreview/blob/main/literati...

which allows me to have an ordinary .tex file:

https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...

which outputs multiple .py and .scad files and generates a .pdf with nice listings-based code blocks, ToC, index, hyperlinks, &c.:

https://github.com/WillAdams/gcodepreview/blob/main/gcodepre...

The notable downsides are that the .sty and .tex files have to be customized for the filenames which one can output, and I haven't been able to get auto-line numbering working between code blocks, so one has to manually manage the counters.

Sorta? Noweb and org mode's support of it, at least, has a "detangle" and it worked surprisingly well last time I tried it. You can't edit the comments it puts in the source, for obvious reasons. And I'm sure it has trouble if you tried to get too fancy. But it did allow me to edit the generated source directly and pull those edits back into my literate source. I imagine if this was something people were more often doing, you could make it more reliable, even.

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.

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.

I prefer to add huge amounts of comments, explaining in as much detail as I can, sometimes it will be a mini-essay in there. I write most of it before I write the code. It helps me formulate the code better. Later it serves as explanatory text.

Usually the problem with comments is that there is too less of it.

Org-babel[1]:

"Literate programming (LP) offers 2 classical operations:

    Tangle: Extract the source code blocks and generate real working code files for further compilation or execution, eventually outside of Emacs.

    Weave: Export the whole Org file as literate, human-readable documentation (generally in HTML or LaTeX)."

[1] https://org-babel.readthedocs.io/en/latest/