Commenting (was: what is unclear about 01 02 03)

[Ed.Doxtator@xxxxxxxxx]

>On Wednesday, May 06, 1998 9:17 AM, Scott Swaim [SMTP:scott71@hpnc.com]
>wrote:
>>With all of this talk about proper coding I have not seen one
>>mention of comment your code for "Others".
Unca Buck responded:
>Scott, you are 10000% correct!!!!
>We try to get our people to write their comments first, then write the
>code around the comments.
Exactly right, in my opinion.  It's so much easier to design code if you
think in a human language and then hang code off that thought.

Whoever said "Comments are great as long as the code isn't obvious," is
being shortsighted.  Comments aren't for YOU, they're for the other newbie
schmuck what has to debug your code.  I always pity the fool who has to
handle my code, and I try to be as kind as possible.  (In the vain hope
that someone will likewise show me the same kindness.)

Finally, I seem to recall reading that once upon a time, HP used to write
rough drafts of their manuals, and then started writing code based on the
manual, rather than the other way around.

I always thought this made a lot of sense in terms of software design.  The
spec is the user manual.  Course... it's always subject to the same sorts
of limitations you get from any design document, bad market requirements,
scope changes, etc.  But at least there was a standard functional document
that told you in the user's terms what the product was supposed to do.

Anyway, just my 2p...

Look after yerselves..

-Doc

n.p.  Frank Black & The Catholics, "Frank Black & The Catholics"


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