Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!ames!haven!uvaarpa!virginia!uvacs!hsd
From: hsd@uvacs.cs.Virginia.EDU (Harry S. Delugach)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Keywords: comments
Message-ID: <2989@uvacs.cs.Virginia.EDU>
Date: 22 Feb 89 06:00:28 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Reply-To: hsd@uvacs.cs.virginia.edu.UUCP (Harry S. Delugach)
Organization: U.Va. CS dept.  Charlottesville, VA
Lines: 54

In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:
> From my point of view, good documentation in
>the form of comments is rare because there is NO WAY of guaranteeing
>that they are correct with respect to the code.  They are a nightmare
>to maintain, and no one ever has the time to fix the comments when the
>code has fatal bugs.  Also, no one wants to take the time to rewrite
>their code into English; it's a boring, tedious job, and when it comes
>down to it only the code really matters to those buying your software.

What about the customer who wants to know why a certain multi-million dollar
company is taking so long to fix a reported bug in their software? What about
the teams of programmers who are trying to understand each other's code in
order to get the product out the door? 

>It is human nature to take the path of least resistance; comments go
>against this path.  With very few exceptions, for better or for worse,
>this is the way of the world.

I think the only way to get programmers to document their code is to convince
them that they gain tangible benefits from including comments in their code.
Sometimes it means having a programmer go back to a year-old program and
try to make efficient changes to it. Sometimes it means getting livid with
anger at the long-gone programmer when you have to maintain his/her 
uncommented code (Do unto others...). No one should include comments because
they're supposed to, or (egad!) required to. They should do it, in the words
of the TV commercial, because it's the right thing to do, like throwing your
trash in the trash can instead of littering.

>What is needed to improve self-documentation are better programming languages.

This is certainly true, but even the "better" programming languages allow for
the inclusion of comments. There will probably always be parts of the 
programmer's concept which need to be expressed in an informal way through
comments.

>There are many instances on where poorly documented code is "worse than
>nothing"; most notably, when the comments are WRONG!  It has happened
>too many times that someone reads the comments on how the routine is
>"supposed to" work, makes a change, and finds out that the
>implementation is totally different than the comments.  I wonder how
>many lost man-years in software maintenance can be attributed to this.

Probably about the same number of person-hours taken up in going to and from
coffee machines in a million software developers' offices. :-) Seriously,
whenever I maintain code with such comments, I make a note to the effect that
the comments may be invalid. Sometimes, I just delete them entirely, so I
guess I agree that poor comments are worse than none. Clearly the best thing
is to add new comments when you make a change.

-- 
                              Harry S. Delugach   
Dept. of Computer Science, Univ. of Virginia, Charlottesville, VA 22901  U.S.A.
        INTERNET: hsd@cs.virginia.edu       BITNET: hsd2x@virginia
        UUCP: ..!uunet!virginia!uvacs!hsd   CIS: 72727,2363