Path: utzoo!mnetor!uunet!husc6!necntc!ima!think!fad
From: fad@think.COM (franklin a davis)
Newsgroups: comp.software-eng
Subject: Re: Comments in programs
Message-ID: <19359@think.UUCP>
Date: 11 Apr 88 14:55:37 GMT
References: <2218@ttidca.TTI.COM> <3850008@wdl1.UUCP> <48869@sun.uucp> <38798UH2@PSUVM>
Sender: usenet@think.UUCP
Reply-To: fad@balder.think.com.UUCP (franklin a davis)
Organization: Thinking Machines Corporation
Lines: 63

In article <38798UH2@PSUVM> UH2@PSUVM.BITNET (Lee Sailer) writes:
>Can someone supply the *exact* citation to Knuth's essay on LITERATE
>PROGRAMMING?
>

Donald E. knuth, "Literate Programming," Dept. of Computer Science,
Stanford University (September 1983).

I wrote a short paper on this while at the Wang Institute, and looked
into the system a bit.  I found Knuth's idea very inspiring -- he
breaks a system into big chunks, and describes each in prose, with
pseudocode.  The pseudocode contains lines that are like macros --
each is further detailed in a following section.  By the time you're
done reading, each piece of the program has been described and coded. 

You can then run the Web processor to produce either TeX source for a
well-formatted text description of the program, or Pascal source.
(There now exists CWeb, which produces troff and C source.) The
central idea is that when the program is modified, both the
documentation and the code are at the same place in the same source
file, so both will be updated in synch.  Producing the new printed or
executable results is then trivial. 

A big assumption of Web's approach is that people know how to design a
program using step-wise refinement.  As I wrote last year,

 "The remarkable thing about his [Knuth's] example is the great ease
 the reader finds in following his elegant approach to creating this
 program.  Each piece is presented in the context in which it is
 relevant, and not before the other pieces that are necessary
 background are presented.  Knuth's ability to break the problem down
 into pieces is dazzling.  However, despite its clarity, the process
 left me feeling that I would have a hard time producing such elegant
 results, even if I had mastered Web."
 
We can't all be Donald Knuths...

I think Web would have a longer learning curve than most languages,
and so is likely to be used by a small set of programmer.  Knuth seems
to support this, concluding, "...Web seems to be specifically for the
peculiar breed of people who are called computer scientists."  As a
software engineer, I personally interpret the distinction in this case
to partly be a matter of time.  Scientists may have time to tinker and
groom an idea or example, but engineers generally have pressing
external deadlines.  

(I'll probably get roasted for that last statement...)

I'll end with another wonderful quote from Knuth's introduction:

 "During the 1970s I was coerced like everybody else into adopting the
 ideas of structured programming, because I couldn't bear to be found
 guilty of writing 'unstructured' programs.  Now I have a chance to get
 even.  By coining the phrase 'literate programming,' I am imposing a
 moral commitment on everyone who hears the term; surely nobody wants
 to admit writing an 'illiterate' program."


--Franklin Davis


  franklin a davis  Thinking Machines Corp. Cambridge, MA 02142   617-876-1111
  <fad@think.com>   {ihnp4, harvard, seismo}!think!fad  "Roll away...the dew!"