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.3 required=5.0 tests=BAYES_00, REPLYTO_WITHOUT_TO_CC 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-17 03:06:02 PST Path: supernews.google.com!sn-xit-03!supernews.com!cyclone-sjo1.usenetserver.com!news-out.usenetserver.com!cyclone-pass-sjo.usenetserver.com!e420r-atl1.usenetserver.com.POSTED!not-for-mail Reply-To: "Peter Richtmyer" From: "Peter Richtmyer" Newsgroups: comp.lang.ada References: <93objj$guk$1@nnrp1.deja.com> <93q77h$rr6$1@nnrp1.deja.com> <940f9j$nj2$1@nnrp1.deja.com> <94299p$8dd$1@nnrp1.deja.com> Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings X-Priority: 3 X-MSMail-Priority: Normal X-Newsreader: Microsoft Outlook Express 5.00.2919.6600 X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2919.6600 Message-ID: X-Complaints-To: abuse@usenetserver.com X-Abuse-Info: Please be sure to forward a copy of ALL headers X-Abuse-Info: Otherwise we will be unable to process your complaint properly. NNTP-Posting-Date: Wed, 17 Jan 2001 06:04:09 EST Organization: WebUseNet Corp http://www.usenetserver.com - Home of the fastest NNTP servers on the Net. Date: Wed, 17 Jan 2001 05:59:51 -0500 Xref: supernews.google.com comp.lang.ada:4087 Date: 2001-01-17T05:59:51-05:00 List-Id: wrote in message news:94299p$8dd$1@nnrp1.deja.com... > In article <940f9j$nj2$1@nnrp1.deja.com>, > peter_richtmyer@my-deja.com wrote: > > [...] > > 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. > > Of course you don't mean that comments are unnecessary in program text, > only that they do not affect the function :-) > Actually, I did mean they are *unnecessary*, meaning *not needed*. They are certainly not required by the compiler. With respect to the human reader, given enough time, and given access to the requirements, design specs, PDl, interface specs, other docs, other people, etc, the program comments are *not needed*. Please don't misunderstand, I tend to be a *comment freak*, writing more lines of comments than code in the programs that I write. I tend to attach words like *lazy*, *discourteous*, and *unprofessional* to programmers I work with who do not adequately comment our code. Though *clue-less* might pertain too. I used the word *our* above very intentionally too. I am talking about our team and our company. No one person owns the code at work. I take pride in my code. But not sole possession. > > In another sub-thread of this discussion, someone stated that document examples and program comments are not *analogous*. I agree. I intentionally avoided the use of the word *analogy*, instead weasle-wording it with the phrase *somewhat similar* (see above). Examples and comments are somewhat similar in that they both make it easier to understand what I am reading (document or program) . They can also make it easier to perform what is quite often the next step, i.e. to create or modify some code. And, of course, the comments. :-) Peter P.S. Why do I keep using * instead of " ? :-)