From:	Robert Watkins robert.watkins@******.com
Subject:	[semi-OT] programming languages' evolution
Date:	Tue, 2 Feb 1999 09:16:59 +1000

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?

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

Java is an example of a programming language set up for literate
programming. You can also get tools for literate programming for C and C++
in Unix (free, of course...). A good IDE that knows about literate
programming will take advantage of it. As an example, check out Microsoft's
J++... function descriptions, parameter descriptions, reminder tags, etc,
are all displayed at appropriate times (e.g.: type a function name, the
description appears in a floating window. Start entering a parameter, a
description of the parameter appears, etc etc). I was so pissed off to see
that Microsoft had built this really cool technology into their J++ (I won't
call it Java) development environment, then left it largely out of their VB
and VC environments, which is where I do my work. Stupid gits.

--
Duct tape is like the Force: There's a Light side, a Dark side, and it
binds the Universe together.
Robert Watkins -- robert.watkins@******.com