Path: utzoo!utgpu!water!watmath!clyde!rutgers!ukma!psuvm.bitnet!uh2
From: UH2@PSUVM.BITNET (Lee Sailer)
Newsgroups: comp.software-eng
Subject: Re: Comments in programs
Message-ID: <38798UH2@PSUVM>
Date: 10 Apr 88 15:11:41 GMT
References: <2218@ttidca.TTI.COM> <3850008@wdl1.UUCP> <48869@sun.uucp>
Organization: Penn Sate Erie--School of Business
Lines: 28

Can someone supply the *exact* citation to Knuth's essay on LITERATE
PROGRAMMING?

Basically, his idea is that comments should explain the code as well
as if they were explanations in a text book, or if you were walking
another programmer thru the code so that he could take over the
development or maintenance.

The WEB system supports this in the extreme.  In WEB, as I understand it,
the programmer writes prose that describes the code to another
human.  When run thru one filter, this WEB file becomes a chapter in
a book about that piece of code, all nicely formatted with the language
keywords in bold, etc.  When run thru a different filter, the WEB
gets reformatted into compilable code.

Notice one advantage of this---the *detailed* doumentation and specification
document and the compiled source code are one and the same.  When a bug
is fixed in the code, the docs change simultaneously.

THE BOTTOM LINE

It is claimed, and supported by a few *small* empirical studies, that
this approach leads to better code faster.  Sort of one-man egoless
programming.

I've seen it work.

                  lee