Re: AWS Coding Styles (and about boring plain-linear text files in the end)

[Adam Beneschan <adam@irvine.com>]

On Jan 18, 12:44 pm, Florian Weimer <f...@deneb.enyo.de> wrote:
> * Adam Beneschan:
>
> > 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.
>
> Huh?
>
> In my version, I've got:
>
> | 9
> |         function To_Unbounded_String (Source : in String)
> |            return Unbounded_String;
> | 11
> |         function To_String (Source : in Unbounded_String) return String;
>
> | 78
> |    * If S is a String, then To_String(To_Unbounded_String(S)) = S.
> |
> | 79
> |    * If U is an Unbounded_String, then
> |      To_Unbounded_String(To_String(U)) = U.
> |
>
> So this description does not use the formal parameter names at all!

Son of a (*&#$(*&, I found the one section of A.4.5 that used names
other than the formal parameter names.  [Note that it doesn't try to
use English text instead of the formal names, but rather substitutes
its own algebra-like variable name.]

OK, then, look at most of the rest of A.4.5, or A.16, or A.10.5 other
than the File parameter.

But I'll take back one thing I said---the RM isn't as consistent as I
thought.  11.4.1 seems to avoid using formal parameter names.  In 3.9,
it looks as though the pre-Ada 2005 material tried to avoid using
formal parameter names, but subprogram descriptions added later did
not.

I'll stand by most of what I said, though.  Much or most of the RM
uses formal parameter names in the descriptions, and I believe that
avoiding formal parameter names gains nothing and often loses.

                                 -- Adam