Noweb – A Simple, Extensible Tool for Literate Programming

Is there a simple intro an ELI5 to get into or learn literate programming?

My current understanding is that if write a paragraph size of comments to explain each and every part of my code with its intent it will be called literate programming.

It depends a lot on what you imagine writing with literate programming, and, like all documentation, who you imagine the reader to be.

When I (used to) write literate programs, the document I produced would be some kind of top-down view of the functionality. I would begin by explaining the kind of problem to be solved and include motivating examples. Then I would explain the structure of the solution and start writing each piece. At the end (perhaps an appendix) I would have the parts where the pieces assembled into the structure required by the compiler.

One of the essential points of literate programming is that it lets you structure your explanation in a way that makes sense, while the literate programming tool outputs "chunks" restructured in a way that makes sense for the compiler.

Perhaps your idea of paragraph sized comments seems silly because you're not imagining something that would be complex enough to comment that way? Imagine a physics simulation. A numerical linear algebra library. Perhaps a game where there are some complex interactions between certain entities that need to be spelled out so that they next person knows what the heck is going on.

Of course there is a level of organization where people write separate design docs for everything, and some level of management has signed off on this or that... I don't think literate programming is for that level of coordination. I think it's for a smaller team, a more personal level of organization and exposition.

BTW, I am pretty sure Norman Ramsey himself has said with many modern programming languages literate programming is no longer essential. The order of presentation of functions, for example, is not constrained in Java. In the olden days (ummm, yes, I know C and its derivatives are alive and well today...), you would need to generate header files and source code, so the signature in the `*.h` file had to match in function in the `.c` file. Better to keep them adjacent in the documentation, at least. But that isn't really the way things look today, at least in my world.

While I agree that things are less necessary in a modern language, I disagree that Java is "unconstrained." This is especially false when one considers that the "entry point" to your code is more dependent on how the framework you are using calls it.

It gets laughable when you have codebases that have "gone all in (functional|object oriented|any other style)" where they seem to mistake the style for the goal, which should be to solve a problem. (I say this as someone that is pretty sure I have made those mistakes.)

There's Knuth's TeX Book and METAFONT Book, and his Stanford GraphBase book. There's also his collection of papers, Literate Programming (https://www.amazon.com/gp/product/0937073806/ref=dbs_a_def_r...).

Knuth has an LP web page (https://www-cs-faculty.stanford.edu/~knuth/lp.html), but it looks like the examples are out of date.

Probably more useful is http://www.literateprogramming.com/; the CWEB Tool page has some examples and the PDF Articles page has ... articles.

Here's an intro from Knuth: http://www.literateprogramming.com/knuthweb.pdf

And then there's Physically Based Rendering at http://www.pbr-book.org/.