Re: Guile docstrings---should Guile code be ANSI C compatible?

[Gregg Reynolds <greynolds at greynolds dot com>]

Tom Burdick wrote:
> 
> On Wed, 5 Jan 2000, Gregg Reynolds wrote:
> 
> > A tuppence:  fwiw, I see this as a good argument for segregating longish
> > comments in a separate file.  The C language is for writing programs,
> > not prose.  Personally I like to see minimal embedded comments when
> > working on code.
> 
> If you haven't, I would highly reccomend reading some of the essays on
> literate programming (esp "Literate Programming" by Knuth).  If you have,
> you've just got a different take on programming than I.
> 

Yes, I'm well familiar with Knuth's ideas and writings; in fact, I
invented "The Somewhat Annual Golden Knuth Prize for Formal Literature"
and awarded it this year to the editors of the proposed ISO Z
definition.  The prize this (oops, I meant last) year was one gallon of
Hans' Homemade Glogg; but the editor in chief never told me where to
send it; I think he thought I was being facetious, but in fact I have
the bottle at home waiting to be sent.  Nominations now being accepted
for the next prize; source code, formal language definitions, design
docs, etc. are eligible; plain old prose technical documentation
generally isn't, since it isn't written using formal languages, but
maybe a separate category should be created for it.  Most beautiful
piece of formal literature wins.

I think I probably have a different take on the notion of a "document"
than you do.  Any decent development environment always supports
multiple edit/browse sessions, some sort of "tags" facility, etc. 
Pragmatically, the only requirement for coding and doc is that the
developer be able to switch from one to the other easily.  Including
prose in a source file as comments is only one way to do this, and not
necessarily the best way.  It's merely a technique, and I can assure you
from long experience on many systems in many languages the proper
maintenance of documentation is a matter of individual and
organizational discipline, not of technique.  Given the right tools
(emacs qualifies), segregating the bulk of documentation from source
code is no less convenient than cramming it into the source.  In other
words, I think of "document" as a network of information whose structure
is distinct from its packaging into files/databases.

Knuth-style LP has virtually never worked on a large project with many
hands.  In fact it is clearly detrimental in one respect, and that is
the division of labor between programmer and tech writer.  It's also
virtually impossible to use it on legacy code.  It also clashes with the
definition of C, which clearly was not designed to support it (cweb is
not c).  But it's the spirit that counts: write source and doco for a
human audience.  I'm confident Knuth himself would encourage the
exploration of alternative practical techniques.

So I've come 'round to the view that minimal (but sufficient!) comments
in source are best.  A variant on "the code should be self-documenting"
(which is usually invoked by programmers with a shaky grasp of prose
composition).  In particular Z looks very promising as a documentation
language; it has formally defined semantics and an easy to read and
write "email" notation.  An example of where Z shines is the r5rs
definition of (string char ...), which only says the new string is
"composed of" the arguments.  Since there is no requirement to maintain
the sequential ordering, a 'string' function the reversed or jumbled the
sequence would be conformant according to this definition.  It would be
difficult to write such a definition in Z.

But to reiterate:  I'm not looking to pick a fight, just bouncing ideas
around.  I'll follow the lead of the maintainer and primary developers
on this.

-gregg