Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!cs.utexas.edu!sun-barr!lll-winken!decwrl!ucbvax!hplabs!otter!adw
From: adw@otter.hpl.hp.com (David Wells)
Newsgroups: comp.software-eng
Subject: Re: Coding standards (was Re: Programmer productivity)
Message-ID: <3490005@otter.hpl.hp.com>
Date: 4 Jan 90 10:48:33 GMT
References: <546@sagpd1.UUCP>
Organization: Hewlett-Packard Laboratories, Bristol, UK.
Lines: 51

>decot@hpisod2 (Dave Decot) writes:
>The questions I want answered by comments are:
>	What do the possible values of this variable or type represent,
>	within the user's abstraction?
>
>[additional good comments and example deleted]
>
>The interesting thing about comments like this is you can grab them straight
>out of a specification document.  >> HINT!!! <<

Exactly. Only a tiny fraction of software can be effectively maintained without
a knowledge of its intended purpose. I look to comments to provide the
following information:

i) How the implementation relates to the next-higher level of specification.
For simple software, this may be the requirements spec., or it may be a
design based on the requirements, etc.

Examples: /* This algorithm positions the dialog box so as not to obscure the
             focussed window (S-12-35 para 3.32) */
          /* Doubly-linked list used here to achieve necessary browsing
             performance (section 5.3.1) */

ii) How the *actual* implementation relates to the *ideal* implementation. Many
languages don't have extensive (or any) support for complex types,
preconditions, postconditions, encapsulation, etc. (If the software is being
developed particularly carefully, there may be a specification at this
"ideal implementation" level, e.g. in pseudocode, and these comments will
reduce to i) above).

Examples: /* "token" must have been obtained from xxAllocate() */
          /* This structure is intended as a link in a doubly-linked list */
          /* This type is PRIVATE to module xx */

iii) WHY the implementation design decisions documented in i) and ii) were
taken. This is most-often-omitted, I think, and often causes frustration and
delay while the maintainer wonders "*why* did he/she do it like *that*!? Was
it a mistake, or was the original developer anticipating a spec. change I
haven't thought of..?" These comments are particularly useful when (as often)
the specification is tightened after "release 1".

Examples: /* singly-linked list used because backward scan speed unimportant */
          /* This table could be compressed, but will probably be small */
          /* Use green menus because it's my favourite colour */

In an ideal world, the comments would be coupled to the code via a tool
(e.g. WEB, folding editors) rather than simply plonked into it, and coupled
to the specification via a hypertext-like tool to facilitate crossreferencing
and allow parallel version-control.

Dave Wells