Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!ames!ucsd!sdcsvax!ucsdhub!esosun!seismo!uunet!jarthur!ssdken
From: ssdken@jarthur.Claremont.EDU (Ken Nelson)
Newsgroups: comp.software-eng
Subject: Re: comments on comments
Summary: Reviews make good internal documentation possible.
Keywords: comments, reviews
Message-ID: <267@jarthur.Claremont.EDU>
Date: 21 Feb 89 16:06:59 GMT
References: <1813@goofy.megatest.UUCP> <20233@agate.BERKELEY.EDU> <4173bd76.183dc@apollo.COM> <9606@ihlpb.ATT.COM>
Reply-To: ssdken@jarthur.UUCP (Ken Nelson)
Organization: Software Systems Design, Claremont, CA
Lines: 41

In article <9606@ihlpb.ATT.COM> nevin1@ihlpb.UUCP (Nevin ":-)" Liber) writes:

>The question is:  Why?  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.
>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.

Right, it is human nature.  However there is a way of ensuring good
documentation of C or any code. The technique is called the "review".  An
independant revview both of the code and the comments, and a software
managers insistence on fixing problems identified in the reviews, will
ensure proper documentation, and also raise the quality of the software
product.  All it takes is devoting a little up-front effort which will
yield large returns in the future as program complexity increases, and as
staff turnover makes orignial authors unavailable.

The reason "no one" wants to take the time to do it right is that "no one's"
team leader or manager did not require, enforce and provide incentives for
good documentation.  The problem is a people problem, not one of programming 
language, although certain languages do lend themselves to better 
documentation.

Software analysis tools can help by automating much of the header information
that becomes out of date (calls, called-by, change notices etc...).  Tools
are not a panacea, but merely a means of complementing a vigorous and 
strictly enforced documentation program that is  based on people doing 
their job correctly.


						Ken Nelson
						Principal Engineer
						Software Systems Design
						(714) 624-2306

In this case the views expressed above are shared by my employer.