Path: utzoo!mnetor!uunet!ncc!alberta!edson!doug
From: doug@edson.UUCP (Doug Konrad)
Newsgroups: comp.software-eng
Subject: Re: American Programmer
Message-ID: <120@edson.UUCP>
Date: 7 Apr 88 16:52:11 GMT
References: <87@studsys.mu.edu> <3850007@wdl1.UUCP> <1664@ur-tut.UUCP>
Organization: Dept. of E.E., U of Alberta, Edmonton,Canada
Lines: 35
Summary: deadlines and self-defense

In article <1664@ur-tut.UUCP>, msir_ltd@ur-tut (Mark Sirota) writes:
> In article <3850007@wdl1.UUCP> rhj@wdl1.UUCP (Bob Jones) writes:
> > 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. 
> 
> Agreed, but allow me to break this up a little further.
> 
> 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.

The problem with Mark's technique arises in situations where there is
significant deadline pressure... Do you really think that adequate time will
be spent commenting code when the boss is breathing down your neck? Even if
the boss grudgingly agrees to allow you the time, how many programmers will
resist the temptation to cut corners (and keep their job) when the boss drops
by their cubicle and says, "Just about done? We've got to finish project 745 -
project 746 is a rush..."

Suggestions that one needs a new boss are not particularily constructive - any
organization must watch its efficiency closely if it is to succeed. Any boss
will have to be careful that his department wastes little time. The difficulty
is that so many people have trouble seeing the work that occurs after a
product seems to work according to spec as crucial as work that occurs before.

So... my suggestion is that you comment while you code. Then, when it runs, its
done.

Doug