LiterateProgramming

My QuoraAnswer https://www.quora.com/Why-is-literate-programming-so-unpopular/answer/Phil-Jones-He-Him

tl;dr It doesn't really solve the problems people have as well as other tools and strategies that are more popular.

The basic idea of literate programming is that documentation is such a good thing that you shouldn't keep it separate from the program but embed the program into the documentation.

The contrary truth is that documentation isn't as wonderful as Knuth assumed. And there are other ways to combine "documentation" with code that have proved more congenial to people, and more effective.

Firstly, well written code ought to, to a certain extent, be clear enough for another programmer to read and understand what's going on. That is the most important thing. Adding natural language descriptions of what your code is doing, alongside that, is a very poor substitute for readable code.

If your code is well written, the next programmer won't need to read a long commentary on it because he or she will be able to follow your code directly.

And if your code isn't well written then

• a) it's unlikely that your attempt to write a natural language description of what it does is much better.
• b) even if your description is wonderfully clear, then the next programmer is still going to have to struggle with your badly written code, just to be able to make sense of the mapping between the clear documentation and the unclear code.

Now he / she has two problems.

However, this should all be understood in a context where a lot more human-readable labelling has moved into programming languages themselves. When Knuth was promoting Literate Programming people were still using languages where you wrote :

LET X = 10
GOTO 5000

And if you didn't comment or document what was going on at line 5000 then the next programmer would have to read another 100 lines of low-level code to know why you even did that.

Today, you're more likely to call a function

 sortedUsers = quicksort(userTable) 

which despite being genuine executable computer code is also 95% human-readable labelling.

So in that sense, documentation DID get integrated with code. But in a different way from the way LP imagines. Languages got a lot higher level (can hide a lot of the computer-oriented mechanism from the programmer), and code now has a far higher proportion of human-readable tokens than it did previously.

Beyond that, the web happened. Suddenly we had access to all the documentation we needed at the click of a hyper-link. When I read someone's code that calls an unfamiliar API I don't need the original programmer to have documented what that API call does for me. Because I can just type two words into Google and see it all. I can see the official documentation. I can see examples of people using it. I can see discussions where people complain about problems with it and suggest workarounds. There's no way that the original programmer, however diligent in his or her literate documentation, could provide a fraction of that value to me.

Finally, when Knuth was promoting Literate Programming, people were still printing out listings (https://www.quora.com/Is-it-unconventional-for-a-programmer-to-sift-through-lines-of-lengthy-code-printed-on-paper-rather-than-on-his-her-screen-in-order-to-find-bugs-and-logical-errors-Why/answer/Phil-Jones-He-Him), to read them offline, and then typing in their modifications (sometimes on punched cards). In that world, Literate Programming made sense. All that you had to work with was the listing that came off the line-printer. Any information that wasn't in that listing wasn't really available to you. So the more information that was in it, the more the programmer explained his or her thoughts and rationales, the better.

That's not a world any of us live in today. Today if we want to know what something does we can type it on the REPL or our IDE lets us drill down to the definition in a library. Our IDEs auto-complete the correct names of things for us. We develop against automated tests which continuously alert us to problems. This is a much faster, more fluid, interactive way of developing software. We develop in a live "conversation" with the computer. We rarely have chunks of time when we step back from the machine and read and contemplate and simulate the running of an algorithm in our heads.

So Literate Programming is a solution for an age which has passed. When the tools were different. When the roles of programmers and computers were different. When documentation was scarce and very hard to access. And the languages were so low level that most of a programming listing was in machine-speak not human-speak.

Today's programming challenges need solutions specific to them.