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,CP1252
Path: 
 g2news1.google.com!postnews.google.com!o14g2000prn.googlegroups.com!not-for-mail
From: Adam Beneschan <adam@irvine.com>
Newsgroups: comp.lang.ada
Subject: Re: AWS Coding Styles (and about boring plain-linear text files in
 the end)
Date: Tue, 18 Jan 2011 11:47:26 -0800 (PST)
Organization: http://groups.google.com
Message-ID: 
 <4dc188a3-468c-40eb-9f3c-85bfb621cb23@o14g2000prn.googlegroups.com>
References: <op.vpfsjkfdule2fv@garhos>
 <24418fa4-8843-4fe6-8c2f-026ea6009b68@g26g2000vbz.googlegroups.com>
 <87lj2ido9j.fsf@mid.deneb.enyo.de>
NNTP-Posting-Host: 66.126.103.122
Mime-Version: 1.0
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable
X-Trace: posting.google.com 1295380050 6728 127.0.0.1 (18 Jan 2011 19:47:30
 GMT)
X-Complaints-To: groups-abuse@google.com
NNTP-Posting-Date: Tue, 18 Jan 2011 19:47:30 +0000 (UTC)
Complaints-To: groups-abuse@google.com
Injection-Info: o14g2000prn.googlegroups.com; posting-host=66.126.103.122;
 posting-account=duW0ogkAAABjRdnxgLGXDfna0Gc6XqmQ
User-Agent: G2/1.0
X-HTTP-UserAgent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.0; WOW64;
 SLCC1; .NET CLR 2.0.50727; Media Center PC 5.0; .NET CLR 3.5.21022; .NET CLR
 3.5.30729; .NET CLR 3.0.30618; .NET4.0C),gzip(gfe)
Xref: g2news1.google.com comp.lang.ada:16524
Date: 2011-01-18T11:47:26-08:00
List-Id: <comp.lang.ada>

On Jan 18, 11:07=A0am, Florian Weimer <f...@deneb.enyo.de> wrote:
> * pascal:
>
>
>
>
>
> >> =A0 =A0 > Comments describing a subprogram spec should specifically
> >> =A0 =A0 > mention the formal argument names. General rule: write a
> >> =A0 =A0 > comment that does not depend on the names of things.
>
> >> =A0 =A0 Q: I am afraid I did not understood this one, as it seems
> >> =A0 =A0 =A0 =A0ambiguous to me. How to refer to formal argument names
> >> =A0 =A0 =A0 =A0without refering to the names of things ? Or else, are
> >> =A0 =A0 =A0 =A0does =93names of things=94 refer to in this context ?
>
> > Instead of saying:
>
> > =A0 =A0procedure Call (Filename : String);
> > =A0 =A0-- =A0The name of the file should be an absolute name
>
> > Say:
>
> > =A0 =A0procedure Call (Filename : String);
> > =A0 =A0-- =A0Filename must be an abosulute name
>
> The problem is that the rule is self-contradictory. =A0I think it should
> say, "should not specifically mention", i.e., the opposite of what you
> suggested.

Maybe that's what the style guide author intended.  If so, I think he
had it completely backward.  Look at the RM's descriptions of what the
subprograms in language-defined packages do, and then try to figure
out how to describe them without referring to parameter names.  Try
Ada.Strings.Unbounded.To_String and To_Unbounded_String, for example,
in A.4.5(78-79).  That's just the first thing I went to when I picked
an Annex A section more or less arbitrarily---I didn't have to hunt
for the "best example".  Anyway, you *could* rewrite the description
in a way that doesn't refer to the parameter names, but all you gain
is verbosity and stilted-sounding language---at the expense of
clarity, readability, and several dozen of your readers' brain cells.

In fact, the RM does this quite consistently, which would make it a
bit odd for a style guide to decide on a "rule" that is exactly the
opposite.  So maybe your suggested fix for this contradiction is the
opposite of what was intended.

                                  -- Adam