Path: utzoo!mnetor!uunet!lll-winken!lll-lcc!ames!oliveb!sun!gravity!klein
From: klein%gravity@Sun.COM (Mike Klein)
Newsgroups: comp.software-eng
Subject: Re: American Programmer (What's a Ph.D. worth?)
Message-ID: <48869@sun.uucp>
Date: 8 Apr 88 17:41:35 GMT
References: <2218@ttidca.TTI.COM> <3850008@wdl1.UUCP>
Sender: news@sun.uucp
Reply-To: klein@sun.UUCP (Mike Klein)
Organization: Sun Microsystems, Mountain View, CA
Lines: 20

In article <3850008@wdl1.UUCP> rhj@wdl1.UUCP (Bob Jones) writes:
|I must stand by my earlier assertion: Comments (in the large)
|should be written before the code.  They serve to assure that
|you know and understand what you are coding.  If you can't 
|describe it in plain English, you probably can't code it in
|a reliable and maintainable fashion either.

This goes together perfectly with my own experiences.  If a module is
commented in plain English (typically with simple "verb-object" descriptive
pairs such as "initialize variables", or "allocate memory structures"),
then the writer has thought about what it is doing and has conceptualized
it well enough to express simply.  At this point, the writer understands
it, I understand it, and anyone else looking over it understands it.  That
means that any bugs, including the more pernicious ones such as logic
errors or oversights, are more easily found.  These comments should, as Bob
says, be done *before* the coding has been finished so that logic and
control flow has been thought out beforehand.
--
Mike Klein		klein@Sun.COM
Sun Microsystems, Inc.	{ucbvax,hplabs,ihnp4,seismo}!sun!klein
Mountain View, CA