From:	Mark A Shieh SHODAN+@***.EDU
Subject:	[semi-OT] programming languages' evolution
Date:	Mon, 1 Feb 1999 19:19:59 -0500 (EST)

"Robert Watkins" <robert.watkins@******.com> writes:
> Mark Shieh writes:
> > > Self-documenting code increases development time, but decreases
> > > maintenance time (things like declaring the type of all variables,
> > > even if you don't really have to)
> >
> > I haven't noticed this to be the case. All self-documenting
> > code does is force you to produce minimal documentation. If you did
> > that anyways, it doesn't make a difference.
>
> Hmm... have you ever done any literate programming?

It appears not. :( I haven't had access to any of the IDE
features you describe, which seem to take self-documenting code from a
minor feature into something useful. I still visualized the
documentation as something that just exists, not something that can
integrate with the code like you describe.

> Literate programming is a logical extension of self-documenting code. You
> actually embed the technical documentation into the program code, as
> comments. You then run a parser over the code to extract the technical
> documentation from the code.
>
> Such a technique does not reduce the amount of documentation you would
> produce, though a bit of discipline is required. And the maintainence cost
> is decreased, because:
> a) Odds are you'll change the comment when you change the code.
> b) You don't have to do that silly management trick of updating comment
> blocks at the start of functions, and then having to update another document
> seperately (which you usually forget about anyway, even though that document
> is the offical technical reference for your program).

We've been producing code for internal use, so our technical
documentation is the comment block at the start of a function. Most
of the techniques you describe sound most useful if you're producing a
library to distribute for commercial use, or the internal equivalent
at a large company. I admit that I haven't had to do any coding on
that scale yet. So far, I haven't had any problems reading the
comments at the start of each function and skimming the code I won't
need to comprehend. (Actually, it hasn't been that simple. Most of
the previous code is undocumented, but I'd rather not talk about
agreed-upon bad SE practices.)

However, I can see a literate programming style becoming
useful when well integrated with an IDE, but all of the
self-documenting tools I've seen have been pretty standalone.

Mark