From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=0.7 required=5.0 tests=BAYES_00,MSGID_RANDY autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,e61c8636ef35379d X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2001-01-15 21:52:03 PST Path: supernews.google.com!sn-xit-03!supernews.com!newsswitch.lcs.mit.edu!feed2.onemain.com!feed1.onemain.com!xfer13.netnews.com!netnews.com!newspeer1.nac.net!news.maxwell.syr.edu!nntp2.deja.com!nnrp1.deja.com!not-for-mail From: Robert Dewar Newsgroups: comp.lang.ada Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings Date: Tue, 16 Jan 2001 05:42:54 GMT Organization: Deja.com Message-ID: <940n0u$tnf$1@nnrp1.deja.com> References: <93objj$guk$1@nnrp1.deja.com> <93q77h$rr6$1@nnrp1.deja.com> <940f9j$nj2$1@nnrp1.deja.com> NNTP-Posting-Host: 205.232.38.14 X-Article-Creation-Date: Tue Jan 16 05:42:54 2001 GMT X-Http-User-Agent: Mozilla/4.61 [en] (OS/2; U) X-Http-Proxy: 1.0 x51.deja.com:80 (Squid/1.1.22) for client 205.232.38.14 X-MyDeja-Info: XMYDJUIDrobert_dewar Xref: supernews.google.com comp.lang.ada:4042 Date: 2001-01-16T05:42:54+00:00 List-Id: 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/