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

["pascal.obry@gmail.com" <pascal.obry@gmail.com>]

Yannick,

> In “3.5 Comments” :
>
>     > The only exception to this rule (i.e. one space is
>     > tolerated) is when the comment ends with --
>
>     Q: Why a comment could ends with “--” ? What could this mean ?

File header (boxed style comment).

> In “3.5 Comments” :
>
>     > Comments describing a subprogram spec should specifically
>     > mention the formal argument names. General rule: write a
>     > comment that does not depend on the names of things.
>
>     Q: I am afraid I did not understood this one, as it seems
>        ambiguous to me. How to refer to formal argument names
>        without refering to the names of things ? Or else, are
>        does “names of things” refer to in this context ?

Instead of saying:

   procedure Call (Filename : String);
   --  The name of the file should be an absolute name

Say:

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


> In “4 Declarations and Types” :
>
>     > Declarations should be grouped in a logical order.
>
>     Q: What about circular dependencies ? I use to think
>        about the same rule for myself, but oftenly failed
>        due to circular dependencies matters (i.e. when there
>        is iterative evaluation as an example).

I would say that "logical" here cover this case. There is now way
around
that anyway.

> In “4 Declarations and Types” :
>
>     > All local subprograms in a subprogram or package body
>     > should be declared before the first local subprogram
>     > body.
>
>     Q: Why this requirement of a declaration for body's and
>        procedure's local subprograms ? Is it to avoid the
>        need to order subprogram bodies with respect to their
>        dependencies to each others ? (if so, this would
>        be contradictory with previous quote).

First this force having a spec and the spec must be commented.
Second it is better to group all specs together for maintenance
and code review. You have all local subprograms in a single
place.

> In “6.2 If Statements” :
>
>     > Complex conditions in if-statements are indented two
>     > characters
>
>     Q: I've already seen about this convention in some other
>        places, while I could never understand it. Not that I
>        disagree, just want to know, because this may mean
>        there is something relevant I've never though about.
>        Is that to shorten line length ? Is that to just have
>        a different indent than the one which come for “when”
>        parts of “case” statements ?

No strong opinion on this one. 2 spaces is shorter than 3 sure, but
as for many convention it is just a convention. Note that this is
what Emacs and GPS does, so helpful I would say.

> Not questions now, personal talks:
>
> In “8 Packages and Visibility Rules” :
>
>     > Do not with two times the same unit, always use the
>     > deepest child unit to with. For example do not write:
>     >            with Ada.Strings;
>     >            with Ada.Strings.Unbounded;
>     > but the equivalent form:
>                  with Ada.Strings.Unbounded;
>
>     I always do the opposite. I feel it is clearer if I
>     refer to the parent unit. If I don't, I do not withed
>     the parent unit (i.e. I state something about usage in
>     the withed declarations).

Fine, just another convention.

> In “9 Packages and Visibility Rules” :
>
>     > It is good to group the context clauses in 3 parts.
>     > The Ada standard clauses, the components from other
>     > projects and then the project's clauses. In each
>     > group it is required to sort the clauses by alphabetical
>     > order.
>
>     Adding some grouping by roles is also nice when the context
>     clause may be long (by the way, the grouping presented in
>     this design guide-lines is compliant with a grouping by
>     roles).

Ok.

> Ah, a big one deal for me this one… (the one which follows)
>
> In “3.1 Character Set and Separators” :
>
>     > A line should never be longer than 79 characters,
>     > not counting the line separator.
>
>     I fully agree with this is some sense (just that I use 78
>     characters instead of 79). But I agree only at the display
>     side, not at the source side. Let me explain

One of the most important points are:

  1. readability, it is hard to read too long line
  2. maintainability, code review as it is almost impossible to read
     a diff for too long lines.

> P.S. Thanks for the “Short comments that fit on a single line are NOT  
> ended with a period.” in “3.5 Comment” : I oftenly had the same question  
> for myself, and could never make a final decision about it. If you decided  
> and make it a standard, well, let's go for this one and follow it.

This is also GNAT standard.

> P.P.S. No, no, I am not to work on AWS source, I was just reading it  
> driven by curiosity. :p

:)

Pascal.