Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!cs.utexas.edu!swrinde!zaphod.mps.ohio-state.edu!tut.cis.ohio-state.edu!ucbvax!ucsd!ucsdhub!hp-sdd!apollo!perry
From: perry@apollo.HP.COM (Jim Perry)
Newsgroups: comp.misc
Subject: Re: Coding standards (was Re: Programmer productivity)
Message-ID: <475e57db.20b6d@apollo.HP.COM>
Date: 11 Dec 89 21:30:00 GMT
References: <473ae701.20b6d@apollo.HP.COM> <5007@netcom.UUCP>
Sender: root@apollo.HP.COM
Reply-To: perry@apollo.HP.COM (Jim Perry)
Organization: Hewlett-Packard Apollo Division - Chelmsford, MA
Lines: 42

In article <5007@netcom.UUCP> hue@netcom.UUCP (Johathan Hue) writes:
>In article <473ae701.20b6d@apollo.HP.COM>, perry@apollo.HP.COM (Jim Perry) writes:
>> Again, you're throwing out the baby with the bathwater.  External
>> documentation has a fundamental flaw alluded to by dopey (no offense): it's
>> not generally there, and it's out of date.  "Most code comments" are also
>> missing or out of date, but only because most code is poorly documented.
>> As Fred Brooks says in The Mythical Man-Month:
>
>One of my rules is "You shouldn't have to look at the code to understand
>what it does and how it works".  If the external documentation isn't
>there, then your programmers have no discipline and your managers are a
>bunch of whimps.  Maybe HP will be able to whip you Apollo boys into shape. :-)

I originally wrote a fairly windy response to this, but on the whole I 
suspect we agree more than we disagree.  For the record, my opinions as
expressed here are based on all of my experiences, and don't necessarily
reflect either policy or practice at HP/Apollo.  Most of my opinions
about good and bad code documentation were formed by experiences
before I came here.

Based on my experience, I've come to the conclusion that code should
be completely self-documenting to the maximum degree possible.  I'm
not saying that there shouldn't be external documentation, but that
it's unlikely, in practice, to keep up with program mutation to the
extent that internal comments are.  Again, this is not to say that
more comments are always better, but there should be sufficient
comments to completely document the code.

I stand by my statement that such programs are possible, and that a
programmer/engineer can use such the documentation in such a
program, as formatted listing on paper or fiche, or just as source
text in your favorite browsing editor, to come quickly up to speed on
that program.  I say this, again, from experience.  

I do use ascii characters to draw box-and-line diagrams, as it
happens.  It's not perfect, but it's better than nothing.  Design
specs and other external documents get fancier Interleaf graphics.

-
Jim Perry   perry@apollo.hp.com    HP/Apollo, Chelmsford MA
This particularly rapid unintelligible patter 
isn't generally heard and if it is it doesn't matter.