gnat-style.texi

来自「理解和实践操作系统的一本好书」· TEXI 代码 · 共 949 行 · 第 1/2 页

     end if;
@end group

@group
     if x = lakdsjfhlkashfdlkflkdsalkhfsalkdhflkjdsahf or else
        x = asldkjhalkdsjfhhfd                         or else
        x = asdfadsfadsf
     then
       ...
     end if;
@end group
@end smallexample

@item
Conditions should use short-circuit forms (@code{and then},
@code{or else}), except when the operands are boolean variables
or boolean constants.
@cindex Short-circuit forms

@item
Complex conditions in @code{if} statements are indented two characters:
@cindex Indentation (in @code{if} statements)

@smallexample @c adanocomment
@group
      if @var{this_complex_condition}
        and then @var{that_other_one}
        and then @var{one_last_one}
      then
         ...
      end if;
@end group
@end smallexample

@noindent
There are some cases where complex conditionals can be laid out
in manners that do not follow these rules to preserve better
parallelism between branches, e.g.

@smallexample @c adanocomment
@group
      if xyz.abc (gef) = 'c'
           or else
         xyz.abc (gef) = 'x'
      then
         ...
      end if;
@end group
@end smallexample


@item
Every @code{if} block is preceded and followed by a blank line, except
where it begins or ends a @syntax{sequence_of_statements}.
@cindex Blank lines (in an @code{if} statement)

@smallexample @c adanocomment
@group
        A := 5;

        if A = 5 then
           null;
        end if;

        A := 6;
@end group
@end smallexample
@end itemize

@subsection Case Statements
@cindex @code{case} statements

@itemize @bullet
@item
Layout is as below.  For long @code{case} statements, the extra indentation
can be saved by aligning the @code{when} clauses with the opening @code{case}.

@smallexample @c adanocomment
@group
       case @var{expression} is
          when @var{condition} =>
             ...
          when @var{condition} =>
             ...
       end case;
@end group
@end smallexample
@end itemize

@subsection Loop Statements
@cindex Loop statements

@itemize @bullet
@noindent
When possible, have @code{for} or @code{while} on one line with the
condition and the @code{loop} keyword.

@smallexample @c adanocomment
@group
       for J in S'Range loop
          ...
       end loop;
@end group
@end smallexample

@noindent
If the condition is too long, split the condition (see ``If
statements'' above) and align @code{loop} with the @code{for} or
@code{while} keyword.
@cindex Alignment (in a loop statement)

@smallexample @c adanocomment
@group
      while @var{long_condition_that_has_to_be_split}
        and then @var{continued_on_the_next_line}
      loop
         ...
      end loop;
@end group
@end smallexample

@noindent
If the @syntax{loop_statement} has an identifier, it is laid out as follows:

@smallexample @c adanocomment
@group
      Outer : while not @var{condition} loop
         ...
      end Outer;
@end group
@end smallexample
@end itemize

@subsection Block Statements
@cindex Block statement

@itemize @bullet
@item
The @code{declare} (optional), @code{begin} and @code{end} words
are aligned, except when the @syntax{block_statement} is named.  There
is a blank line before the @code{begin} keyword:
@cindex Alignment (in a block statement)

@smallexample @c adanocomment
@group
      Some_Block : declare
         ...

      begin
         ...
      end Some_Block;
@end group
@end smallexample

@end itemize

@c  -------------------------------------------------------------------------
@node    Subprograms, Packages, Statements, Top
@section Subprograms
@c  -------------------------------------------------------------------------
@cindex Subprograms

@subsection Subprogram Declarations
@c  -------------------------------------------------------------------------
@itemize @bullet

@item
Do not write the @code{in} for parameters.

@smallexample @c adanocomment
      function Length (S : String) return Integer;
@end smallexample

@item
When the declaration line for a procedure or a function is too long to fit
the entire declaration (including the keyword procedure or function) on a
single line, then fold it, putting a single parameter on a line, aligning
the colons, as in:

@smallexample @c adanocomment
@group
     procedure Set_Heading
        (Source : String;
         Count  : Natural;
         Pad    : Character := Space;
         Fill   : Boolean   := True);
@end group
@end smallexample

@noindent
In the case of a function, if the entire spec does not fit on one line, then
the return may appear after the last parameter, as in:

@smallexample @c adanocomment
@group
      function Head
        (Source : String;
         Count  : Natural;
         Pad    : Character := Space) return String;
@end group
@end smallexample

@noindent
Or it may appear on its own as a separate line. This form is preferred when
putting the return on the same line as the last parameter would result in
an overlong line. The return type may optionally be aligned with the types
of the parameters (usually we do this aligning if it results only in a small
number of extra spaces, and otherwise we don't attempt to align). So two
alternative forms for the above spec are:

@smallexample @c adanocomment
@group
      function Head
        (Source : String;
         Count  : Natural;
         Pad    : Character := Space)
         return   String;

      function Head
        (Source : String;
         Count  : Natural;
         Pad    : Character := Space)
         return String;
@end group
@end smallexample

@end itemize

@subsection Subprogram Bodies
@c  -------------------------------------------------------------------------
@cindex Subprogram bodies

@itemize @bullet
@item
Function and procedure bodies should usually be sorted alphabetically. Do
not attempt to sort them in some logical order by functionality. For a
sequence of subprogram specs, a general alphabetical sorting is also
usually appropriate, but occasionally it makes sense to group by major
function, with appropriate headers.

@item
All subprograms have a header giving the function name, with the following
format:

@smallexample @c adanocomment
@group
      -----------------
      -- My_Function --
      -----------------

      procedure My_Function is
      begin
        ...
      end My_Function;
@end group
@end smallexample

@noindent
Note that the name in the header is preceded by a single space,
not two spaces as for other comments. These headers are used on
nested subprograms as well as outer level subprograms. They may
also be used as headers for sections of comments, or collections
of declarations that are related.

@item
Every subprogram body must have a preceding @syntax{subprogram_declaration}.

@item
@cindex Blank lines (in subprogram bodies)
A sequence of declarations may optionally be separated from the following
begin by a blank line.  Just as we optionally allow blank lines in general
between declarations, this blank line should be present only if it improves
readability. Generally we avoid this blank line if the declarative part is
small (one or two lines) and the body has no blank lines, and we include it
if the declarative part is long or if the body has blank lines.

@item
If the declarations in a subprogram contain at least one nested
subprogram body, then just before the @code{begin} of the enclosing
subprogram, there is a comment line and a blank line:

@smallexample @c adanocomment
@group
    --  Start of processing for @var{Enclosing_Subprogram}

    begin
      ...
    end @var{Enclosing_Subprogram};
@end group
@end smallexample

@item
When nested subprograms are present, variables that are referenced by any
nested subprogram should precede the nested subprogram specs. For variables
that are not referenced by nested procedures, the declarations can either also
be before any of the nested subprogram specs (this is the old style, more
generally used). Or then can come just before the begin, with a header. The
following example shows the two possible styles:

@smallexample @c adanocomment
@group
    procedure Style1 is
       Var_Referenced_In_Nested      : Integer;
       Var_Referenced_Only_In_Style1 : Integer;

       proc Nested;
       --  Comments ...


       ------------
       -- Nested --
       ------------

       procedure Nested is
       begin
          ...
       end Nested;

    --  Start of processing for Style1

    begin
       ...
    end Style1;

@end group

@group
    procedure Style2 is
       Var_Referenced_In_Nested : Integer;

       proc Nested;
       --  Comments ...

       ------------
       -- Nested --
       ------------

       procedure Nested is
       begin
          ...
       end Nested;

       --  Local variables

       Var_Referenced_Only_In_Style2 : Integer;

    --  Start of processing for Style2

    begin
       ...
    end Style2;

@end group
@end smallexample

@noindent
For new code, we generally prefer Style2, but we do not insist on
modifying all legacy occurrences of Style1, which is still much
more common in the sources.

@end itemize


@c  -------------------------------------------------------------------------
@node    Packages, Program Structure, Subprograms, Top
@section Packages and Visibility Rules
@c  -------------------------------------------------------------------------
@cindex Packages

@itemize @bullet
@item
All program units and subprograms have their name at the end:

@smallexample @c adanocomment
@group
      package P is
         ...
      end P;
@end group
@end smallexample

@item
We will use the style of @code{use}-ing @code{with}-ed packages, with
the context clauses looking like:
@cindex @code{use} clauses

@smallexample @c adanocomment
@group
      with A; use A;
      with B; use B;
@end group
@end smallexample

@item
Names declared in the visible part of packages should be
unique, to prevent name clashes when the packages are @code{use}d.
@cindex Name clash avoidance

@smallexample @c adanocomment
@group
      package Entity is
         type Entity_Kind is ...;
         ...
      end Entity;
@end group
@end smallexample

@item
After the file header comment, the context clause and unit specification
should be the first thing in a @syntax{program_unit}.

@item
Preelaborate, Pure and Elaborate_Body pragmas should be added right after the
package name, indented an extra level and using the parameterless form:

@smallexample @c adanocomment
@group
      package Preelaborate_Package is
         pragma Preelaborate;
         ...
      end Preelaborate_Package;
@end group
@end smallexample

@end itemize

@c  -------------------------------------------------------------------------
@node    Program Structure, GNU Free Documentation License, Packages, Top
@section Program Structure and Compilation Issues
@c  -------------------------------------------------------------------------
@cindex Program structure

@itemize @bullet
@item
Every GNAT source file must be compiled with the @option{-gnatg}
switch to check the coding style.
(Note that you should look at
@file{style.adb} to see the lexical rules enforced by
@option{-gnatg}).
@cindex @option{-gnatg} option (to gcc)
@cindex @file{style.adb} file

@item
Each source file should contain only one compilation unit.

@item
Filenames should be 8 or fewer characters, followed by the @code{.adb}
extension for a body or @code{.ads} for a spec.
@cindex File name length

@item
Unit names should be distinct when ``krunch''ed to 8 characters
(see @file{krunch.ads}) and the filenames should match the unit name,
except that they are all lower case.
@cindex @file{krunch.ads} file
@end itemize


@c **********************************
@c * GNU Free Documentation License *
@c **********************************
@include fdl.texi
@c GNU Free Documentation License
@cindex GNU Free Documentation License

@node Index,,GNU Free Documentation License, Top
@unnumberedsec Index

@printindex cp

@contents

@bye