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 only have a little bit of experience with literate programming, but that's because I wasn't very impressed with it. I think that JavaDoc-style comments are better, because they give you the option of reading the comments in the code or looking at generated documentation.

Answer 2

(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.