Xref: utzoo comp.software-eng:2637 comp.misc:7612
Path: utzoo!utgpu!jarvis.csri.toronto.edu!cs.utexas.edu!mailrus!uflorida!novavax!twwells!bill
From: bill@twwells.com (T. William Wells)
Newsgroups: comp.software-eng,comp.misc
Subject: Re: Coding standards (was Re: Programmer productivity)
Message-ID: <1989Dec7.202908.10192@twwells.com>
Date: 7 Dec 89 20:29:08 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> <1989Dec4.222725.5920@athena.mit.e <1989Dec5.1
Organization: None, Ft. Lauderdale, FL
Lines: 53

In article <32359@watmath.waterloo.edu> sccowan@watmsg.waterloo.edu (S. Crispin Cowan) writes:
: In article <1989Dec5.115934.24535@twwells.com> bill@twwells.com (T. William Wells) writes:
: >I'll add my two cents about commenting. I am a big fan of
: >*useful* comments. And I despise over-commenting. The latter is
: >any comment that is not the former.
: I don't understand the problem with over-commenting.  First of all, it
: is _very_ rare (both :-) and :-(), and secondly, just skip it if it
: bugs you.

This is the syndrome where someone writes:

	/* Increment a. */

	++a;

Such comments don't help, but they do waste the time needed to
read them. You don't know ahead of time whether the comment is
important, so you have to read it. To no purpose.

This particular kind of commenting is all too common.

: >I have three simple rules:
: [good list of three rules]
:
: I also like to see ALL variables described.  I can figure out what a
: for-loop is doing, but it's not at all obvious what the
: trans_rec_count variable is a count of (total transactions, to-date,
: how many gropple-grommits in this shipment, etc.).  Unless it's just a
: scratch counter such as `i', it should be commented.

     1) Comments should explain the purpose of the code and its
	relationship to the rest of the program.

applies to variables as well as executable code. BTW, I follow a
consistent rule when commenting variables. If the variable needs a
complex description, that goes before the declaration. On the
declaration goes a short comment which indicates what the variable
is; that comment is always a noun phrase with any leading
determiner deleted.

I'll add a fourth rule to my list:

     4) Comments are literary objects; write them with your
	audience in mind. Write clear and standard English (or
	whatever). Avoid unnecessary abbreviations and ellipses.
	Read a few good books on writing and take at least *some*
	of their suggestions to heart; Strunk & White's _The
	Elements of Style_ is, at least, short and entertaining
	(not to mention useful) and there are many others.

---
Bill                    { uunet | novavax | ankh | sunvice } !twwells!bill
bill@twwells.com