Re: Code Documentation

Subject: Re: Code Documentation
From: "Steven J. Owens" <puff -at- NETCOM -dot- COM>
Date: Thu, 5 Nov 1998 22:21:08 -0800


> There are few things as annoying, when reading code left behind by the last
> programmer, as line after line of documentation that restates what the code
> says, but never mentions why the code is there in the first place, or how it
> fits in the grand scheme of things.

Just as annoying when I find it user guides; command descriptions
like "The File...Save command saves the file". are incredibly
annoying. I know why they end up in the guide - I've been there

It's the week before you have to shove the book out the door to
get it printed in time for the ship date, you're *still* waiting
for a clear explanation of the menu from the developer, anything
you write will the authoritative reference and you have to write
*something* or your boss will give you all kinds of grief about

...and the developer never gets back to you before the end of the
week, so it ends up going out with that text. Understandable, but
still annoying when you're up at 4 in the morning trying to find
something that'll explain how the application *works*.

Seeing it in comments is just as annoying; I can see the code is
setting the blah variable to 4, but what I want to know is *why*
it's doing it...

> Side note on the example: the rather copious use of the word "instantiate"
> is a case of knowing the audience. For programmers, there is nothing at all
> wrong with the word, and it is the right word. At this point in a program,
> there is typically a lot of instantiating going on, so the word gets used a
> lot. You could do a "sportscaster" on it, but that would take a long time to
> write and annoy the reader.

Instantiate - "create an instance of". It's a very logical (if a
bit hard to say) term that the Object Oriented Programming field came
up with. OOP defines classes of objects and their behaviors, then
creates instances of the classes in the system, and starts them
interacting. In many ways it's analogous to initialize ("define the
existence of and usually the initial value of a variable), as used in
more classical programming terminology.

Steven J. Owens
puff -at- netcom -dot- com

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: Code Documentation
Next by Author: Re: Question about Consulting
Previous by Thread: Re: Code Documentation
Next by Thread: FW: Code Documentation

What this post helpful? Share it with friends and colleagues:

Sponsored Ads