Path: utzoo!mnetor!uunet!vsi!friedl
From: friedl@vsi.UUCP (Stephen J. Friedl)
Newsgroups: comp.software-eng
Subject: Re: American Programmer
Message-ID: <503@vsi.UUCP>
Date: 8 Apr 88 00:12:33 GMT
References: <87@studsys.mu.edu> <3850007@wdl1.UUCP>
Organization: V-Systems, Inc. -- Santa Ana, CA
Lines: 19

In article <3850007@wdl1.UUCP>, rhj@wdl1.UUCP (Bob Jones) writes:
> Adding comments as you go is the only way to fly. It may require a
> small amount of additional time up front, but the payoff is huge down
> the road.  Poorly commented code is, in my personal opinion, one of 
> the key indicators of an immature and impatient programmer.

Very good point.  I have found that writing function-header
comments *before* writing the described function helps in two
ways: (A) it insures that the comments go in and (B) it helps me
define *exactly* what the function does.  I describe aloud to an
imaginary officemate what the function does, then put that
description in the comment.  Many times I would need some
function but would have only a general idea what it was supposed
to do.  The documentation ahead of time helps me nail down those
important little details (resets the counter or not, closes the
file or not, increments the pointer or not, etc.).
-- 
Steve Friedl   V-Systems, Inc.   "Yes, I'm jeff@unh's brother"
friedl@vsi.com  {backbones}!vsi.com!friedl  attmail!vsi!friedl