Path: utzoo!utgpu!news-server.csri.toronto.edu!rutgers!usc!wuarchive!uunet!zephyr.ens.tek.com!gvgpsa!gvgspd!mrk
From: mrk@gvgspd.GVG.TEK.COM (Michael R. Kesti)
Newsgroups: comp.misc
Subject: Re: MEL - A *Real* Programmer
Keywords: Real Programmer, Hacker
Message-ID: <1283@gvgspd.GVG.TEK.COM>
Date: 31 Oct 90 18:54:51 GMT
References: <1990Oct23.235720.16178@nas.nasa.gov> <6089@nisca.ircc.ohio-state.edu> <54296@brunix.UUCP> <5777@suned1.Nswses.Navy.MIL> <8187@gollum.twg.com>
Reply-To: mrk@gvgspd.GVG.TEK.COM (Michael R. Kesti)
Distribution: usa
Organization: The Grass Valley Group, Grass Valley, CA
Lines: 27

In article <8187@gollum.twg.com> dwh@twg.com (Dave W. Hamaker) writes:
>It has been my experience, on code I don't have to worry about others having
>to maintain, that documenting each program...

How can you ever be certain that nobody other than yourself will have to
maintain your programs?  I feel that one should try to code as if one
might get run over by a truck on the way home tonight!

>                          I think it is possible to go too far also, where
>a comment can be less than useless, because it tells you nothing useful yet
>you have to read it to find that out.  An example might be:
>
>	++i;	/* increment the index variable */

The problem with this type of comment is that it answers the question "What
did you do?" rather than the more important "Why did you do it?"  I usually
depend on the reader to be able to figure out what, but rarely why.

Just to add fuel to the fire, I think that using "i" (or any other single
letter name" for a variable is horrible practice.  Try searching for all
occasions of it in a function!

-- 
============================================================================
Michael Kesti  Grass Valley Group, Inc. | "Like one and one don't make two,
    mrk@gvgspd.GVG.TEK.COM              |  one and one make one."
    !tektronix!gvgpsa!gvgspd!mrk        |         - The Who, Bargain