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

["Randy Brukardt" <randy@rrsoftware.com>]

"Georg Bauhaus" <rm.dash-bauhaus@futureapps.de> 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.