Xref: utzoo comp.software-eng:2606 comp.misc:7572
Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!mailrus!ukma!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: <1989Dec5.115934.24535@twwells.com>
Date: 5 Dec 89 11:59:34 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.edu>
Organization: None, Ft. Lauderdale, FL
Lines: 31

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 have three simple rules:

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

     2) Comments should explain the *abstract* character of the
	code.

     3) Comments should *never* explain how the code works or what
	it is doing *unless* you have done something tricky.
	(Tricky: if, six months later, after reading the comments
	and the code you have to think about it, it is tricky.)

BTW, the abstract character of the code and its purpose, while
they can usually be explained simultaneously, are not always
close enough that this will work. A routine that converts binary
time to a useful printable form (this is its abstract character)
might have as its purpose permitting printing binary time
usefully; in that case, one comment easily enough serves two
purposes. On the other hand, you might have this complicated date
conversion routine whose character would be described by its I/O
relationships. However, the purpose of the routine might be: "to
satisfy the wants of our VP from Alpha Centauri". :-)

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