Path: utzoo!utgpu!utstat!jarvis.csri.toronto.edu!mailrus!iuvax!rutgers!pyrnj!mirror!garison
From: garison@mirror.UUCP (Gary Piatt)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <23356@mirror.UUCP>
Date: 16 Feb 89 15:42:10 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Reply-To: garison@prism.TMC.COM (Gary Piatt)
Organization: (dis-)
Lines: 31

>Forcing programmers to write more comments is not the answer.  What
>is?

The solution is to give these programmers their own code after four
or five years, and have them modify it (Note: MODIFY, not RECREATE).
In one of my former lives (in 1984), I was called upon to change the
terminal emulation software I had written to allow it to access multiple
display pages.  I had done this four years prior to that day, and
decided to save myself a day's work by resurrecting the older code
and modifying it to fit the new environment.  Well, it didn't work 
that way.  The comments on the old code were what you would refer to
as "sparse" ("This loads the new page" at the head of twenty lines of
code).  Instead of saving time, I ended up wasting time; it took me
the entire day to understand what I had written only four years before.
No matter how good a programmer you are, or how long you've been in
the business, you can't expect yourself to remember the intent of every
line of code you've ever written.

These days, I comment (almost) every line, and WHEN I CHANGE THE CODE,
I CHANGE THE COMMENT.  When I'm done with the program, and I know that
it works, I take the time to add headers to each function, describing
what it does and how it works.  This method has paid off.  Last year 
the company I worked for in 1984 called me back as a consultant to fix
an obscure little bug they had discovered in the software I had written
that year.  I quoted them a price (and they paid me) for the entire day,
but -- because of those comment -- the job only took two hours.

			-garison-


...good comments are like good sex:  too much is never enough