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=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Thread: 103376,429176cb92b1b825 X-Google-NewGroupId: yes X-Google-Attributes: gida07f3367d7,domainid0,public,usenet X-Google-Language: ENGLISH,ASCII-7-bit From: "Randy Brukardt" Newsgroups: comp.lang.ada Subject: Re: AWS Coding Styles (and about boring plain-linear text files in the end) Date: Tue, 18 Jan 2011 16:13:15 -0600 Organization: Jacob Sparre Andersen Message-ID: References: <24418fa4-8843-4fe6-8c2f-026ea6009b68@g26g2000vbz.googlegroups.com> <87lj2ido9j.fsf@mid.deneb.enyo.de> <4D35F6C8.2060100@obry.net> <4d3608ab$0$7664$9b4e6d93@newsspool1.arcor-online.net> NNTP-Posting-Host: static-69-95-181-76.mad.choiceone.net X-Trace: munin.nbi.dk 1295388798 7620 69.95.181.76 (18 Jan 2011 22:13:18 GMT) X-Complaints-To: news@jacob-sparre.dk NNTP-Posting-Date: Tue, 18 Jan 2011 22:13:18 +0000 (UTC) X-Priority: 3 X-MSMail-Priority: Normal X-Newsreader: Microsoft Outlook Express 6.00.2900.5931 X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.5931 X-RFC2646: Format=Flowed; Original Path: g2news2.google.com!news4.google.com!proxad.net!feeder1-2.proxad.net!feed.ac-versailles.fr!news.ecp.fr!news.jacob-sparre.dk!pnx.dk!not-for-mail Xref: g2news2.google.com comp.lang.ada:17505 Date: 2011-01-18T16:13:15-06:00 List-Id: "Georg Bauhaus" wrote in message news:4d3608ab$0$7664$9b4e6d93@newsspool1.arcor-online.net... > On 18.01.11 21:23, Pascal Obry wrote: >> >> Florian, >> >>> The problem is that the rule is self-contradictory. I think it should >>> say, "should not specifically mention", i.e., the opposite of what you >>> suggested. >> >> No, it is definitely "should specifically mention". We are talking about >> the formal name here. Please reread my response to Yannick about this >> one. >> > > The trouble here is maybe that the guidelines say > > 1) Mention the formal argument names! > > 2) Do not depend on the names of things! > > I first thought of the distinction between "to mention" and > "to use" and how it is usually found confusing and thus > frequently accompanied by a definition. Which one is appropriate here? > > Second, the style rule requires thinking about an apparent > contradiction, created by a certain reading of (2) in the > presence of (1). The reader assigns possibly unintended, > yet plausible, meaning to the words "depend" and "names", > and concludes: > > "How is one to mention formal argument names in a comment > but such that one must not depend on names in the comment?" I agree. (I'm working on the Ada standard right now, so I'm reading things fairly formally.) Indeed, I still have no idea what the second sentence of that style section is supposed to mean. I thought it meant the exact opposite of the first sentence (with which I agree wholeheartedly) -- the only way *not* to depend on the names is to not include them in the text. I'd probably suggest dropping it altogether -- I have no idea how to write a useful comment that doesn't depend on the names of things. Perhaps the point was that there always should be a comment (rather than expecting the name of the parameters to serve in place of a comment) -- in that case, the text needs to emphasize the need for comments rather than the reason for omitting them. Randy.