Re: Documentaion Services

[DAsmussen <DAsmussen@xxxxxxx>]

Bradley,

In a message dated 98-05-19 18:34:23 EDT, you write:

<<snip overcommented code stuff>>
> I'd like to look through your source.  No hardcoding anywhere?  I don't
>  believe that for a second.  It would be nice, but sometimes.. well.. it
>  just doesn't work out like that.

Other than named constants, eliminating hard-code is _NOT_ rocket science.
Generally, the first thing I do when I get to a new site (if they haven't
already done it themselves) is to establish a "Generic Codes" Table and an API
to read it.  Send the API a function parameter to either validate the code,
read all codes for a given table, or close files and shut down, and you're
set.  All those things you used to hard code are now flexible and modifiable
without changing code or DDS...

>  I hope that you were getting at _documenting_, not commenting.  I could
>  see how if you write an application and don't document what it does,
>  there could be a problem.

More often than not, you have to threaten coders with termination in order to
get any kind of commenting _OR_ documentation at _all_.  As your own
expository on the subject suggests, code documentation is something that most
of us rail against.  Unless you come from a formal package development
background (or have just been burned enough times over the years), the
importance of documentation is not immediately apparent.  I'm with Tim
(although I _would_ give you a second chance).  Document or die -- and I'll
kill you myself (done it before, and they couldn't find a jury to convict)!
Of course, the "bloody glove" screwed up my mouse to the point that it
couldn't be used again ;-)...

Regards!

Dean Asmussen
Enterprise Systems Consulting, Inc.
Fuquay-Varina, NC  USA
E-Mail:  DAsmussen@aol.com

"Education's purpose is to replace an empty mind with an open one." -- Malcolm
S. Forbes
+---
| This is the Midrange System Mailing List!
| To submit a new message, send your mail to MIDRANGE-L@midrange.com.
| To unsubscribe from this list send email to MIDRANGE-L-UNSUB@midrange.com.
| Questions should be directed to the list owner/operator: david@midrange.com
+---