Re: [Ada] Add GNAT Coding Style Guidelines

[Florian Weimer <fw at deneb dot enyo dot de>]

Geert Bosch <bosch@gnat.com> writes:

> + @item
> + A line should never be longer than 79 characters, not counting the line
> + separator.

This documentation file contains a few very long lines, BTW.

> + It is ok to make a few abbreviations, 

Nice self reference. ;-)

+ The words "Access", "Delta" and "Digits" are capitalized when used

@code{Access} or @samp{Access}?

> + Comment start with @code{--  } (ie @code{--} followed by two spaces).

You should use @samp instead if @code here, giving a more readable
result in this particular case.

> + @item
> + 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. The names are supplementary, not
> + sufficient, as comments.

What about the verb in the first sentence of a subprogram description?
Should it be an imperative or not?  An example from the Ada Reference
Manual:

| 100. function Slice (Source : in Bounded_String;
|                      Low    : in Positive;
|                      High   : in Natural)
|         return String;
| 
|      101. Returns the slice at positions Low through High in the string
|           represented by Source; propagates Index_Error if Low >
|           Length(Source)+1.

I think you could write "Return the slice...", too.  Or you could
repeat the function name.  Perhaps a preference should be documented?

> + @item
> + Do not declare discriminated record types where the discriminant is used
> + for constraining an unconstrained array type. (Discriminated
> + records for a variant part are allowed.)

Why this rule?  The other rules are quite obvious or subject to taste,
but this one seems to be different.  Is it a code generation issue?

> + @item
> + Do NOT put two spaces after periods in comments.

D'oh!  (You should use Texinfo markup here, though.)

> + @item
> + Don't declare multiple variables in one declaration that spans lines. 
> + Start a new declaration on each line, instead

A point is missing at the end of this sentence.

> + @item
> + Every "if" block is preceded and followed by a blank line, except
> + where it begins or ends a sequence_of_statements.

The preceding part of this not followed in the sources in all cases.
"elsif"s are preceded by blank lines in many cases.

> + The (optional) "declare", "begin" and "end" statements are aligned,
> + except when the block_statement is named:
> + 
> + @smallexample
> +       Some_Block : declare
> +          ...
> +       begin
> +          ...
> +       end Some_Block;
> + @end smallexample

You should document that in a "declare" block, the "begin" is preceded
by a blank line.

> + @item
> + If declarations of a subprogram contain at least one nested subprogram
> + body, then just before the begin is a line:
> + 
> + @smallexample
> +         --  Start of processing for bla bla
> + 
> + 	begin
> + @end smallexample

Which begin? "bla bla" is a placeholder for what?