I really wish Literate Programming had caught on.

The big problem is folks misunderstood it as documentation (arguably plain.tex should have also been the sourcecode for _The TeXbook_ and that it wasn't is a big part of this) --- it could be, but usually that's better as a separate text/chapter....

I've been trying to collect books on Literate Program/notable Literate Programs published as books:

https://www.goodreads.com/review/list/21394355-william-adams...

and I will note that my own programming took a quantum leap forward when I purchased and read:

https://www.goodreads.com/book/show/39996759-a-philosophy-of...

and applied its principles one chapter at a time to a project which I was able (w/ a bit of help) to get into Literate Programming form:

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

There was a phase, which I also got sucked into at the time, that comments are bad. Problem is, to make your code be so self-explanatory that it conveys business decisions, background stories for how you've arrived here, research-based choices made, you would have to name your variables and functions in a batshit_insane_way_that_obfuscates_behavior_among_the_names. It doesn't make anything better.

Use short names where they're contextually clear. Use long names where they're contextually weird/non-belonging. Use comments to explain the "whys" of your code.

I still code this way.