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

[Georg Bauhaus <rm-host.bauhaus@maps.futureapps.de>]

On 1/18/11 11:13 PM, Randy Brukardt wrote:
> "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.

> [...] 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.

My guess was similar.  When names will need to be changed,
the comments can otherwise stay intact:

    procedure Call (Filename : String);
    --  Filename must be an abosulute name

becomes

    procedure Call (Path : String);
    --  Path must be an abosulute name

(I am not suggesting that Path is better than Filename.)
However, when the name becomes "Frmbloo", as in

    procedure Call (Frmbloo : String);
    --  Frmbloo must be an abosulute name

the comment shows that it does depend on the names of things:
The "file" part has gone missing, leaving a blank that the reader
cannot fill in by inference from either the name or from the comment.
What is a Frmbloo?

The comment specifically mentions the formal argument name,
as should be.  However, the comment does depend on the name of
things.