Xref: utzoo comp.software-eng:2650 comp.misc:7627
Path: utzoo!attcan!uunet!snorkelwacker!apple!netcom!hue
From: hue@netcom.UUCP (Johathan Hue)
Newsgroups: comp.software-eng,comp.misc
Subject: Re: Coding standards (was Re: Programmer productivity)
Message-ID: <5007@netcom.UUCP>
Date: 9 Dec 89 06:57:47 GMT
References: <473ae701.20b6d@apollo.HP.COM>
Followup-To: comp.misc
Organization: NetCom- The Bay Area's Public Access Unix System {408 997-9175 guest}
Lines: 32

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. :-)

> Well, of course this is the heart of the matter.  A few-hundred or few-ten
> line program tells us very little about real life software engineering
> situations.  Actually, if the code is properly self-documenting, then the
> new hire *can* just sit down with the code and learn from the code itself. 
> Documentation, like code, is hierarchical.  At the beginning of each
> program, library, whatever, is a broad overview of that unit.  More
> specific comments would be associated with modules, functions, algorithms,
> etc.

I'm sorry, this just doesn't work for me.  If you're going to read the
code you're going to have several hundred to several thousand page
listing, and are going to be forever flipping through it trying to trace
the flow of control and read your comment boxes which describe what your
functions do.

I once worked on a device driver and in the external documentation I drew a
state machine of how one part of it worked.  Are you going to use ascii text
graphics to draw boxes and arrows and put that in your comments?

-Jonathan