Path: utzoo!mnetor!uunet!lll-winken!lll-lcc!ames!sgi!wdl1!rhj
From: rhj@wdl1.UUCP (Bob Jones)
Newsgroups: comp.software-eng
Subject: Re: American Programmer
Message-ID: <3850007@wdl1.UUCP>
Date: 5 Apr 88 17:55:16 GMT
References: <87@studsys.mu.edu>
Lines: 33

Some observations on commented code:

> What a great idea!  How many times have you heard (or said!) in
> school "Yea, I'm done with the program, now I have to put in the
> comments".  Even after almost three years of heavy commercial
> development I am still learning how to put in good documentation
> that *means* something to a maintainer (i.e., me) a year down the
> road.  Students need to learn what the word "maintenance" means...
> 
I have been writing code for over twenty years, now and couldn't agree
more with the above sentiments.  My basic rule of thumb is:

	I always maintain a healthy paranoia of having to maintain 
	my own code. 

Healthy comments make this paranoia managable.

In 1978 and 1979, I wrote Tandem's DDL compiler.  In 1986 I returned
to Tandem as a consultant to help enhance the DDL compiler.  The 
comments I wrote in '79-'79 made it possible for me to relearn the
code very easily.  And the places I had failed to comment came back
to haunt me.

The premise that one will put comments in later is in a class with
comments like "the check is in the mail".  Believers in this premise
most likely still believe in the tooth fairy. 

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.

Bob Jones
Ford Aerospace