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

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

On 1/19/11 10:56 PM, Yannick Duchêne (Hibou57) wrote:
> Le Wed, 19 Jan 2011 14:17:56 +0100, Georg Bauhaus <rm.dash-bauhaus@futureapps.de> a écrit:
>> No, no, the brackets @{ @}, or the line-of-code indicator @@ are much
>> simpler than FunnelWeb. For one thing, the Ada programmer only needs
>> to understand Ada and will not think about typesetting or macros or
>> line endings.
> Where you said “typesetting”, did you meant “semantic markup” ?

(I meant typesetting.  A few bits of FunnelWeb are made for
typesetting.  I wouldn't want to drag these in.)

The very simple addition of @{ and @} to Ada comments would not
have semantic implications.  It is only about making references
to Ada text explicit.  Consider:

   procedure P (ARG : in out TYP);
   -- bla bla @{ARG@} bla bla

Assume further one rule which states whether comments are written
before or after associated Ada program text.

First, the current situation is not very different.
Ada programmers cannot explicitly indicate identifiers
in comments, due to lack of syntax.  But they can and do
mention the function of a word.  Stated explicitly, it
would read:

   procedure P (ARG : in out TYP);
   -- bla bla denoted by formal argument name ARG should bla bla

It is customary to abbreviate this phrase: A convention of contemporary
English makes us assume that a capital letter at the start of a word
(or an underscore within it), occurring in the middle of a sentence,
would imply an Ada item and not the word of spoken language.

Alas, this implicitness doesn't work for ARG in this particular example,
since the program text uses a convention of all caps for identifiers.
The Ada Rapporteur Group meaning is another plausible interpretation,
possibly creating further confusion in the reader's head.
The convention doesn't work in some other spoken languages.
It doesn't work for some words of English.

The syntactical bracketing, @{ARG@}, leaves no doubt as to
which entity the comment is about.


> Also, I did not really understood the last sentence. He/she did not, because he/she should not or he/she don't while he/she should ?

A programmer who writes @{Frmbloo@} will think that he/she
is making the word Frmbloo stand for the identifier and for nothing
else.  Hence, there is no need to think about anything but Ada.