Intuitive motivation for Literate Programming?

Question

So, I used the scribble/lp module to write my first literate program using plt-scheme:

#lang scribble/lp
(require scribble/lp)

<<lp_scheme.ss>>

@chunk[<squarefunction>
        (define (f x)
         (* x x))]

Nothing useful there, of course. Now I am sort of wondering why would I just not use plain comments, instead of literate programming constructs. Any opinions welcome. It would be really great if some one who have probably had more exposure/exp. with it to possibly give a more intuitive explanation of the differences between well documented code and code written using Literate programming constructs.

Answer 1

(I'm assuming you're using Donald Knuth's definition of literate programming.)

The key difference is one of sequence.

In writing a regular application, there are restrictions on the order in which you express things.

To illustrate:

• All code for a particular class has to be expressed in one place
  (or in a very small number of places, e.g. C# partial classes)
• All the code for one method has to be given in one go, in the correct order for execution
• Dependencies must be declared before the things dependent upon them
  (variables declared before use in most languages; procedures/functions declared before use in Pascal; library assemblies compiled before others in .NET)

With literate programming you are freed from this restriction and freed up to express your concepts in whichever order makes sense for you to use when explaining the program to another developer.

This has another consequence - in some forms, you can express a concept once (say, "All properties will fire the PropertyChanged event when changed"), and have that woven throughout your application in a myriad of other places.

For very simple programs, a literate program and a well commented one might look the same - but as the complexity of the system grows, the two will start to appear very different.

Answer 2

Main motivation, as for me, is that every programmer use paper sheets/notebook to 'design' architecture, develop ideas, there he writes schemes, diagrams, try some math and so on. After finishing of the program, all of these notebooks/paper sheets are lost, so supportability of the program is getting down. I wrote about this in WiKi of my LP tool NanoLP: http://code.google.com/p/nano-lp/wiki/AboutLP.

Second motivation, not so explicitly, is lesser bugs. But this is not 'theoretical' thing, it's experience fact (for me) - when you're 'thinking' on the paper, drawing diagrams, algorithms schemes - your program will have lesser bugs. LP is such 'paper', nothing else.

There are many developers, who never draws something, no comments even (!), they write program only... Terrible!

And LP helps you to create good documentation (not in formal way - description on functions, it's args, and what it returns, and sure this is good known with function signature, so why such documentation is needed??), but it helps to write REAL ACTUAL documentation with semantic, with pictures, with describing of real actions...

Many motivations :) And sure sometimes is better to use only reverse LP (Doxygen, for example), sometimes - real LP, depends on many factors.

Answer 3

Literate Programming is based on three simple statements:

1. Programmers must write code, which the computer can understand
2. Programmers should write documentation, which people can understand
3. If these are separate documents it is inevitable that they will be out-of-sync

Indeed, in my experience, #2 usually gets short shrift. I've lost count of how many times QA has told me "the doc says this, but the code does THAT; is the code incorrect or is the doc out-of-date?" I don't expect my workplace is out of the ordinary, in that respect. Additionally, in one of my early projects, I was trying to keep the docs up-to-date as the back-and-forth with the stakeholders resulted in changing requirements. This was sufficiently time-consuming that I was told, by management, to stop messing with the docs and just get the project working. We've gone to less-tedious documentation processes, since then (thank heavens!).

We have code review tools where, when we make a change to the code, multiple people can see the changes, clearly delineated, and comments can be made, asking questions, explaining stuff, offering improvements. If the code was written with Literate Programming techniques, much of this question/answer would be superflous because the explanation would be included.

Much of the mindset of modern programming is that your code should be its own documentation. Many pundits argue that, if you find yourself needing to explain your code in comments, you should probably reformat the code (changing variable/function names, etc.) such that the comments are unneeded. I find this to be great in theory, less practical in reality. I mean, when I'm using libraries created/maintained by someone else, their choice of method/function names isn't always intuitive to me. For example:

Set<String> statesWeCareABout = new HashSet<String>(Arrays.asList(new String[] { "one", "two", "three" }));
Set<String> statesWeFound = <some function>;
statesWeFound.retainAll(statesWeCareAbout);

If you aren't familiar with Set<> or HashSet<>, you may not know that .retainAll() means give me the intersection of the two, with the result in the modified Set<>.

Finally, Literate Programming usually lets you break things down so that you can explain this piece of code in isolation, then in-line it into this other piece of code. This is more in-line with how human comprehension works. Explain to me how this works, then build on that understanding to explain the larger picture. Computers don't really care; you can write a single function with 1,000 lines of code and it has no problem comprehending the whole thing. God help you if you, as a developer, have to maintain that.

And that, really, is the reasoning behind Literate Programming. Code will need to be maintained, whether it's bugs being fixed or features being added. And if it can't be comprehended by someone else, later on, in an efficient fashion, it will be replaced. There is way to much "write only" code in this world. Literate Programming makes it easier to read and comprehend, which makes it more likely to be kept and used, long-term.

And do we really have time to keep re-inventing the wheel?