Why isn't literate programming mainstream? [closed]

Question

Literate programming has good ideals. Why do you think that this isn't mainstream? It is because it has failed to deliver?

Answer 1

I first saw it in a book of Knuth's writings, and thought it looked neat. Then I tried to use the literary programming display to comprehend what was going on in the program, and found it harder than it looked. It may have been that I was too used to going through program listings, but it seemed confusing.

Then I looked at the source code, and that turned me off then and there. I'd have to learn to write programs in an entirely new way, with less correspondence between the program text and what the compiler saw, and saw no corresponding benefit.

In addition, people can write long and convincing arguments that the code is doing X when it's actually doing Y, and I've run into my share of misleading comments. I developed a fondness for reading the code to see what it's doing fairly early. Literate programming is the antithesis of that.

Answer 2

I would blame the network effect. For other people to edit your code and documentation, they must be able to understand it.

This pushes people away from something like cweb/noweb, because using them would require you to learn TeX and the program-specific syntax on top of the programming language you are using for the project. This can be seen as a huge waste of time, especially if they don't need any of the math typesetting that is such a big draw for TeX in the first place. (And for many applications programmers, they really won't need it.) Instead they prefer something like Visual Studio's XML comments, because that's already popular and well-established.

The places I have seen literate programming take off are in scientific/statistical computing, where most of the programmers have significant training (aka PhDs) in math, CS, or statistics, and thus are already famliiar with LaTeX. The documentation they write is more likely to include a lot of complicated formulae that are best written in TeX, and they are more likely to be programming in R. The proportion of R programmers who know about SWeave is definitely much higher than, say, the proportion of C programmers who know about cweb.

Answer 3

I was fascinated by the concept of Literate Programming in the late 90'es while studying, and I am still intrigued with Knuths approach to programming, and typesetting. Nothing but the best will do.

The Literate Programming system that Knuth designed did much, much more than immediately meets the eye, namely it overcome many shortcomings in the underlying programming language that the code generation tool generated from Knuths source document, namely standard Pascal.

For those fortunate enough not to have tried Standard Pascal, here are some of the highlights.

• To make it easier to have a single-pass compiler, the language specification said that all declarations had to come in a certain order. From the wikipedia page: "Each procedure or function can have its own declarations of goto labels, constants, types, variables, and other procedures and functions, which must all be in that order." This meant you could not group your things logically together in the source file.
• String handling was more tedious than in plain C.
• Identifiers could not have arbitrary length.
• Many more things I cannot remember anymore.

All these things basically meant that Knuth needed a better programming language (so he invented one) and it used Pascal as its assembly language.

Most modern languages can do these things without much effort, therefore removing a LARGE part of the work that Literate Programming were to solve.

Also modern languages are more expressive allowing more thought to be put in the code itself.

So, what is left? The ability to generate a typeset form of documentation from the source code, and THAT exists today.

Just think JavaDoc - the Java runtime API is perhaps the largest piece of Literate Programming available today (except that the code isn't actually presented, but it COULD have been if Java was open sourced from the start). See for instance the presentation of the collections framework on http://download.oracle.com/javase/6/docs/api/java/util/Collection.html

I believe similar systems exist for .NET and other mainstream programs.

Answer 4

One thing I discovered when I had my fling with literate programming in the 90s was that it attracted very passionate people who wanted to do Exactly The Right Thing - and that involved writing their own literate programming system because no existing one was good enough for them. noweb was a good attempt to cut that off by providing a good-enough least common denominator for everyone, although even then, I spent most of my LP time developing a pretty-printer for it...

Another issue is that it is really anti-agile. In some ways, being slowed down is good because it forces you to think more up-front and get things right the first time. On the other hand, meticulously documenting as you go means that there's a large barrier to refactoring your code. And if you wait until your code is hardened before you LP-ify it, you end up with a multi-day documentation task, which can really stop you in your tracks.

Answer 5

In my humble opinions, many companies have a culture who is the opposite to the objectives of Literate Programming: they want faster results (they only cry about quality when the app is in production). In my own experience, my bosses had refuse to understand that faster results doesn't mean "a program runnable the day after I asking for." For them, if a developer isn't busy typing over his keyboard, he isn't working, is "wasting his time in design-non-sense". Yes, I know, my boss is an arsehole.

Answer 6

Coders write code not English.

Coders don't like writing documentation because it doesn't help the code run.

Coders aren't good at writing documentation because its a poor medium to express their ideas.

Literate programming seems to be the idea of taking documentation to the next level where the code is more of an after-thought. Maybe it would work, but to most coder it looks like obnoxious documentation.

Answer 7

Principally because people are VERY STUPID. Obvious testimony to which is an endless stream of guesses and misunderstandings expressed by young people about the nature of this simple technique.

People take LP to be: (a) a method of documentation (b) a method of writing some polished essays that necessitates some special skills or talents (c) simply have no clue - as the creator of Leo programming editor, by his own admission etc. etc. etc.

LP however is simply: (1) writing programs in a mixture of code and phrases in a (=any) human language, where the latter stand for other chunks of code and/or included phrases. This is precisely what authors of innumerous programming textbooks do.. and (2) it is a simple preprocessor that expands those phrases in human (which became as if names of included subroutines) to unravel the result IN THE ORDER REQUIRED BY THE COMPILER (or interpreter). Otherwise one can expand the written text with another small utility to include formatting symbols to turn the "literate source" into a nice well-formatted readable text.

Young people never try this extremely simple idea - and either fantasize or imagine fake reasons why they'll never try or do it.

Basically the main idea of programming "in pseudocode" written in a human language and then expanding it with a simple preprocessor utility HELPS MANAGE ATTENTION (limited, a main difficulty for any longish program), pretty much like code folding or division of your program flow into functions/subroutines, needed for you not to lose yourself in the details, but wholly unnecessary for the machine execution.

Answer 8

There are 2 aspects of literate programming that I do wish were incorporated into mainstream programming -- embedded imagery (e.g., design diagrams) and pointers to previous and alternate attempts (e.g., "The reason it's like this is because I tried this other way and it didn't work because ..."). Both of those aspects can be handled with doc-comments and URIs.

Answer 9

Because the logic of programs does not work the same as we speak. A program has a well specified flow, and conditions, and loops.

After having coding at lot, I THINK in these terms. My brain transforms problems into the target domain of executable code. And it is much more efficient for me to write this down in a usually programming language, than having to do the extra transform step to make my programs literate.

In fact, I believe my programs already are literate... speaking identifiers, good function names, comments where I did some hackery which i wouldn't comprehend immediately myself after a few months.

To conclude: My Java code is more literate by itself as every "literate" programming wants to be.

Answer 10

I came to literate programming the other way around - I dreamed having the code organized as it fits my mind, not as the compiler requires it. I found Leo almost ideal for this purpose. It also supports keeping track of files changed outside. These files do not have to contain any special markup, so I can use Leo for myself without any need for others in the team to know. This feature - "@shadow trees" - is very promising, although still bit buggy, needs more eyeballs. And it also fixes the "oh no, everything in one big file" problem both by organizing everything into tree outline and by support for external files.

For me, contrary to the name, the "literate programming" is not about documentation at all. I don't have more documentation than before. It is about having structure that helps me to not become lost. I swear by it especially when managing behemoth JSP files (and that despite Leo was originally intended primarily for Python and it does not have support for JSP language - I have to split the file to Leo tree manually !).

Answer 11

I see it as a valuable teaching tool, where a dissertation on code can be written, and then snippets of working code interleaved in it to instruct readers on the hows, whats, and whys of the code.

Outside a purely educational environment, I think only Knuth really understands how best to use it.

Answer 12

It's the worst of all worlds - you have to write a highly correct, highly specific computer program in a very non-specific language = english. So you have to carefully write it using exactly the correct phrases - so you might as well just write code.