Path: utzoo!mnetor!uunet!lll-winken!lll-tis!ames!sgi!wdl1!rhj
From: rhj@wdl1.UUCP (Bob Jones)
Newsgroups: comp.software-eng
Subject: Re: American Programmer (What's a Ph.D. worth?)
Message-ID: <3850008@wdl1.UUCP>
Date: 7 Apr 88 17:59:37 GMT
References: <2218@ttidca.TTI.COM>
Lines: 53

Responding to comments by:
	/ msir_ltd@ur-tut (Mark Sirota) / 11:03 pm  Apr  5, 1988 /

> I *never* add in-line comments until I'm done writing and testing the
> algorithm or procedure in question.  There is such a thing as
> over-commenting, and the threshold is much lower when the code is
> incomplete.  Sometimes comments just get in the way and make the code
> harder to read, so I generally prefer a "how" and "why" (as opposed to
> "what") comment at the top of a section of code, with nothing inside.
> "what" comments can be added later, as appropriate, to clarify complicated
> code for the future.
> 
> So I think it's a mistake to make a blanket claim that adding comments
> later reflects an immature programmer; sometimes it simply makes more
> sense to do it that way.

Let me categorize comments into four groups:

	1) Descriptive comments on the entire module
	2) Descriptive comments at the begining of each function
	3) Block comments at the begining of significant sections
	   of logic
	4) Line comments describing a variable or line of code

I would agree with Mark's observation about the value of putting
some  comments in after the algorithm is completed, but I would
insist that the function header and module header comments should
always preceed the writing of the code itself.  This doesn't
necessarily mean that you write these comments only once and
never update them; however, if you don't know what a function
or a module (i.e. a collection of related functions) is going
to do before you start writing the code, then you really have
not thought the problem through well enough to start coding it.

I find that the very act of writing the comments forces me to
think the problem through; and I often find that while I am
writing these function level comments, I see a design problem 
that I can still correct easily.  Correcting it after it has
been coded is much harder.

The block logic comments can be put in either before or after
you have coded the logic without much impact on the end result.
Line level comments are not of much use, except as used to
describe variables or standard definitions.


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.

Bob Jones
Ford Aerospace