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

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

In article <940f9j$nj2$1@nnrp1.deja.com>,
  peter_richtmyer@my-deja.com wrote:
> Robert Dewar said:
>
> > Note: for my own taste, I hate to present-by-
> > example, and I hate examples, but my experience is most
> > people like examples.
> > For instance, most people want MORE examples in
> the RM, I
> > regard them as irritating redundant (well
> hopefully redundant)
> > non-normative junk :-)
>
> This statement surprised me a little at first.

Be careful to note that I was just expressing my
own personal viewpoint. As I said, and as I say
in what is quoted above, I quite understand that
most people *do* like examples, and indeed many
people find it very difficult to read language
rules without examples. So I am all in favor of
providing examples, and you will see loads of
examples in the GNAT documentation (particularly
in the specs of the GNAT.xxx library).

Note however, that there is a danger which is
to let examples take the place of thorough
rules. Some people seem to think they can
replace full semantic descriptions by examples,
and *that* is surely a mistake.

> I have saved a comment of yours where you said
> that you *liked* to document code, and encourage
> others to do so. You said that, if you do it
> enough, you can get to enjoy it (or words to that
> effect.) Putting examples in documents is
> somewhat similar to putting comments in code. It
> is not necessary, but it sure makes it easier for
> the readers.

I am not sure there is really any specific connection
between examples in documents and comments in code.
Comments in code are descriptions of what the code
does and why and how it does it. Examples may be
often be useful in this connection if some obscure
piece of code in GNAT for instance is to handle some
particular obscure use of the language, it is often
helpful to readers to provide examples.

Going back to my original comment, I again stress that
I perfectly well understand that my taste is not typical
here. I doubt there are many people who learned COBOL
from the ANSI standard (as I did :-)

> But then, I have written documents that I thought
> were pretty clear, only to find that others
> needed examples to understand them.

Yes, as I say, many people *do* need examples. However,
there is a danger that there understanding is limited to
the examples, and is not comprehensive. Actually there are
few programmers who really thoroughly know the semantics
of the language they are using.

> But code and
> documents should be written for the reader.
> (Yes, I know that that is not an original thought
> on my part). :-)

The right way to look at comments in code is to
think of it as a text book, and yes, of course
comments are written for the user. If something
is not clear in the code, there is a bug in the
comments and it needs to be fixed, and it is the
reader not the writer who is the arbiter of what
is clear.

We always encourage new people coming into the
GNAT project to make comments on what was NOT
clear to them in the code, since they have a
fresh eye and a more useful perspective in some
respects.

I don't think we really disagree on anything
here (though we may have personally different
tastes with respect to language definitions :-)


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