Re: Examples in Docs, was Re: Escape Sequences in Strings

[Robert Dewar <robert_dewar@my-deja.com>]

In article <942brr$b0t$1@nnrp1.deja.com>,
  mark_lundquist@my-deja.com wrote:

> Not a connection, an analogy.  With respect to the function
> of a program, comments are superfluous; with respect to the
> language definition, examples are superfluous.

I disagree strongly with this analogy.

In the case of a language definition, examples indeed convey
no information that cannot be derived from the definition
proper (unless the definition is incomplete). Yes, they may
be helpful in understanding, but they do not have any
non-derivable information.

With comments in a program, the situation is quite different.
Yes, they do not provide any additional information with regard
to what the program does at the implementation loevel, but
*that is NOT the purpose of comments*. The purpose of comments
is to explain what the code is doing at a higher level of
abstraction, and much more importantly WHY it is doing it that
way (and in some cases, very importantly why it is NOT doing it
some other way). You cannot even derive the specification of a
program from the implementation (since the code typically
embodies an over-specification). You for SURE cannot derive the
motivation and high level abstract design from the code.

Indeed if you write comments that CAN be derived from the code,
as in:

   a := a + 1;   -- increment a

then you have written a junk, completely useless comment.
Indeed I would say that comments like this are what are
analogous to examples in programming language definitions :-)


Sent via Deja.com
http://www.deja.com/