Xref: utzoo comp.software-eng:2710 comp.misc:7830
Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!uflorida!rex!samsung!uunet!portal!cup.portal.com!ts
From: ts@cup.portal.com (Tim W Smith)
Newsgroups: comp.software-eng,comp.misc
Subject: Re: Coding standards (was Re: Programmer productivity)
Message-ID: <25518@cup.portal.com>
Date: 31 Dec 89 10:51:21 GMT
References: <Nov.18.22.47.26.1989.9685@paul.rutgers.edu>
  <34796@regenmeister.uucp> <2226@jato.Jpl.Nasa.Gov>
  <128179@sun.Eng.Sun.COM> <546@sagpd1.UUCP> <4727@netcom.UUCP>
  <9157@hoptoad.uucp> <473ae701.20b6d@apollo.HP.COM>
Organization: The Portal System (TM)
Lines: 47

In article <9157@hoptoad.uucp> tim@hoptoad.UUCP (Tim Maroney) writes:
>Absolutely.  Clear code shouldn't *need* a lot of comments; a
>programmer should be able to read it and understand what's going on
>from the routine names, the variable names, and the flow of control,
>with just a few added comments if any.  A lot of extraneous comments
>about things that would be perfectly clear just from reading the code
>actually damages code readability; the control structures become much
>harder to follow.

I tend to agree.  When I code, I tend to comment on the difficult parts,
and leave the obvious parts to speak for themselves.  On the other hand,
something that may be obvious to me because of my several years of
experience may not be obvious to a junior member of the staff who is
getting his first look at whatever arcane thing is being dealt with.

So, what should one do?  Include a lot of "extraneous" stuff to help
the jr. guys, or should one be minimalist to avoid distracting the
other sr. engineers when they look at the code?

I think we came up with a pretty good solution to this problem
where I work.

The comments in the source code are aimed at a person who has a
detailed knowledge of the field that the code is part of.  For
example, if the code was a Unix disk driver, it is assumed that
the person reading the code is an expert on Unix disk drivers.

Part of the final documentation for any code we write is something
we call "left hand pages".  This is a detailed commentary on the
code written by the implementor of the code.  We call it "left hand
pages" because we print a copy of the source code and put it in a
binder together with the "left hand pages" in a way that causes
one to have the source code on the right and the commentary on the
left.

The LHPs are aimed at a much lower level.  For example, if the code
is for a Unix disk driver, the LHPs would assume that you can spell
"Unix" and know that by "disk" we don't mean "Frisbee".  Well, perhaps
not quite this low a level...:-).

For example, a recent Unix disk driver we did had about 45k of source
code.  The LHPs came to about 120k.

As a side effect, we've discovered that quite a few bugs are found
when the implementor is producing the LHPs.

						Tim Smith