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

Mark A Shieh writes:
> When I think of selfdocumenting code, I'm thinking of stuff
> written with something like Javadoc as part of the spec, not code
> where it should be intuitively obvious what's going on just by looking
> at undocumented code. (Which, IIRC, was one of the basic concepts
> around C. :P ) If my terminology is off-base, please correct me. I
> don't believe in the existence of fully selfdocumenting code, so I
> assume we're talking about something like forcing Javadoc into your
> spec, which just isn't going to change the way you do things. Either
> you wrote legible code before, and you'll do it despite Javadoc, or
> you didn't, and you'll have a bunch of illegible code with Javadoc
> stubs. I feel really silly documenting a variable called
> "OrderWindow" with the comment, "this is the pointer that stores the
> OrderWindow for the UI.", but Javadoc wants you to spend that effort.

The problem isn't generally with variables. It's more commonly with
functions, and I don't mean their internals...

Good documentation should let you treat a function totally as a black box:
enter these inputs, you get this output, and these side effects occur. And
functions do have side effects... for example, a SaveToDisk function takes
inputs of a file name, a block of data, and a size parameter. It returns a
status code indicating success or what type of failure. The side effects may
be that it creates a file, deletes the old one if necessary, and writes out
data to disk.

When you write the function spec, you'll typically be writing the technical
documentation, and then you'll write the code. If you have to change the
code, you could very well change what the function actually does, so you
have to update the documentation. This is easier if the documentation is in
the code already.

The other point about documentation is that it should say why you're doing
it. Sure, I can read a program and say: Yep, you're walking through this
array, setting data values. But why are you doing it? Legible code (which is
what is meant by self-documenting code) doesn't describe this.

If you don't have documentation, I can assure you that you are not writing
complex programs, which have to be written by multiple people, and
maintained by different multiple people who don't have your level of
programming skill anyway... On the other hand, I don't mean that you should
be putting comments like this (which I have actually seen):

int LoopCounter; // A loop counter.

// Set LoopCounter to Zero
LoopCounter = 0;

.
.
.

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