Date: Wed, 7 Jun 1995 09:00:53 -0400
From: kagel AT quasar DOT bloomberg DOT com
To: dj
Cc: kentl AT bdc DOT cirrus DOT com, djgpp AT sun DOT soe DOT clarkson DOT edu
Subject: Re: PS: VOTE: CODE STANDARDS
Reply-To: kagel AT ts1 DOT bloomberg DOT com

   Date: Tue, 6 Jun 1995 22:20:37 -0400
   From: dj AT delorie DOT com (DJ Delorie)
   Cc: djgpp AT sun DOT soe DOT clarkson DOT edu

   > Formal, written coding standards are for idle middle managers
   > who aren't smart enough or flexible enough to read other people's
   > code.

   Just today, my manager (at work) called and said that *her* manager
   wanted a functional spec and design document for a program I was
   working on, so they could see what it would look like before I started
   writing it.  I told her it (the program) was already done, and if she
   still wanted a spec I could send her some screen dumps and a copy of
   the source code.

   I've found that writing specs almost always takes longer than just
   writing the code in the first place, and the code usually comes out
   better that way.

   DJ

OK, I've finally been drawn in to this discussion enough to comment.  I give
the benefit of my 14+ years of professional programming experience (not to take
away from anyone else's of course  :-> ).

For many projects, planning and spec'ing are more effort than they are worth,
true.  However, if a project is of any size, or complexity, the specs and
structure charts or flow charts are necessary to keep the code clean and will
pay for the required effort in simplified maintenance later.  Believe me, I do
plenty of code-now-document-later programming where appropriate.  I prefer
prototyping.  But, for larger or more complex systems there comes a point, once
the problem is well understood, where the prototype must be put aside, and at
least the overview and lowest level interfaces must be determined and
documented.  In addition I use Nassi-Schneiderman (or Chapin) structure charts
rather than flow charts and find that they force me to code in a structured
manner.

As to commented code.  Yeah, it is a pain to do, but, "the life you save may be
your own".  Six months or a year later you will not remember why you inserted a
particular block of code, or why you repeated that calculation instead of just
adding in the variable you saved the result in the first time.  I agree with
someone on this thread who said that comments should state the "why" not the
"how".  I would add, though, that the comments should also state the "what",
just because what you were trying to accomplish  was obvious to you does not
mean that it will be to that newbie who will inherit it in a year!

P.S.  I HATE CODE STANDARDS.  [Especially since they NEVER agree with the
standards I would have set!?!?!   :-)]

Enough!

-- 
Art S. Kagel, kagel AT ts1 DOT bloomberg DOT com

Variety is the soul of pleasure.  --  Aphra Behn