Skip several gcc.dg/builtin-dynamic-object-size tests on hppa*-*-hpux*

[official-gcc.git] / gcc / ada / doc / gnat-style.rst

GNAT Coding Style: A Guide for GNAT Developers
==============================================

General
-------

Most of GNAT is written in Ada using a consistent style to ensure
readability of the code.  This document has been written to help
maintain this consistent style, while having a large group of developers
work on the compiler.

For the coding style in the C parts of the compiler and run time,
see the GNU Coding Guidelines.

This document is structured after the Ada Reference Manual.
Those familiar with that document should be able to quickly
lookup style rules for particular constructs.

Lexical Elements
----------------

Character Set and Separators
****************************

.. index:: Character set
.. index:: ASCII
.. index:: Separators
.. index:: End-of-line
.. index:: Line length
.. index:: Indentation

* The character set used should be plain 7-bit ASCII.
  The only separators allowed are space and the end-of-line sequence.
  No other control character or format effector (such as ``HT``,
  ``VT``, ``FF`` )
  should be used.
  The normal end-of-line sequence is used, which may be
  ``LF``, ``CR/LF`` or ``CR``,
  depending on the host system.  An optional ``SUB``
  ( ``16#1A#`` ) may be present as the
  last character in the file on hosts using that character as file terminator.

* Files that are checked in or distributed should be in host format.

* A line should never be longer than 79 characters, not counting the line
  separator.

* Lines must not have trailing blanks.

* Indentation is 3 characters per level for ``if`` statements, loops, and
  ``case`` statements.
  For exact information on required spacing between lexical
  elements, see file style.adb.

  .. index:: style.adb file

Identifiers
***********

* Identifiers will start with an upper case letter, and each letter following
  an underscore will be upper case.

  .. index:: Casing (for identifiers)

  Short acronyms may be all upper case.
  All other letters are lower case.
  An exception is for identifiers matching a foreign language.  In particular,
  we use all lower case where appropriate for C.

* Use underscores to separate words in an identifier.

  .. index:: Underscores

* Try to limit your use of abbreviations in identifiers.
  It is ok to make a few abbreviations, explain what they mean, and then
  use them frequently, but don't use lots of obscure abbreviations.  An
  example is the ``ALI`` word which stands for Ada Library
  Information and is by convention always written in upper-case when
  used in entity names.

  .. code-block:: ada

           procedure Find_ALI_Files;

* Don't use the variable name ``I``, use ``J`` instead; ``I`` is too
  easily confused with ``1`` in some fonts.  Similarly don't use the
  variable ``O``, which is too easily mistaken for the number ``0``.

Numeric Literals
****************

* Numeric literals should include underscores where helpful for
  readability.

  .. index:: Underscores

  .. code-block:: ada

          1_000_000
          16#8000_0000#
          3.14159_26535_89793_23846

Reserved Words
**************

* Reserved words use all lower case.

  .. index:: Casing (for reserved words)

  .. code-block:: ada

           return else

* The words ``Access``, ``Delta`` and ``Digits`` are
  capitalized when used as attribute_designator.

Comments
********

* A comment starts with ``--`` followed by two spaces.
  The only exception to this rule (i.e. one space is tolerated) is when the
  comment ends with a single space followed by ``--``.
  It is also acceptable to have only one space between ``--`` and the start
  of the comment when the comment is at the end of a line,
  after some Ada code.

* Every sentence in a comment should start with an upper-case letter (including
  the first letter of the comment).

  .. index:: Casing (in comments)

* When declarations are commented with 'hanging' comments, i.e.
  comments after the declaration, there is no blank line before the
  comment, and if it is absolutely necessary to have blank lines within
  the comments, e.g. to make paragraph separations within a single comment,
  these blank lines *do* have a ``--`` (unlike the
  normal rule, which is to use entirely blank lines for separating
  comment paragraphs).  The comment starts at same level of indentation
  as code it is commenting.

  .. index:: Blank lines (in comments)
  .. index:: Indentation

  .. code-block:: ada

           z : Integer;
           --  Integer value for storing value of z
           --
           --  The previous line was a blank line.

* Comments that are dubious or incomplete, or that comment on possibly
  wrong or incomplete code, should be preceded or followed by ``???``.

* Comments in a subprogram body must generally be surrounded by blank lines.
  An exception is a comment that follows a line containing a single keyword
  ( ``begin``, ``else``, ``loop`` ):

  .. code-block:: ada

           begin
              --  Comment for the next statement

              A := 5;

              --  Comment for the B statement

              B := 6;
           end;

* In sequences of statements, comments at the end of the lines should be
  aligned.

  .. index:: Alignment (in comments)

  .. code-block:: ada

            My_Identifier := 5;      --  First comment
            Other_Id := 6;           --  Second comment

* Short comments that fit on a single line are *not* ended with a
  period.  Comments taking more than a line are punctuated in the normal
  manner.

* Comments should focus on *why* instead of *what*.
  Descriptions of what subprograms do go with the specification.

* 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.

* *Do not* put two spaces after periods in comments.

Declarations and Types
----------------------

* In entity declarations, colons must be surrounded by spaces.  Colons
  should be aligned.

  .. index:: Alignment (in declarations)

  .. code-block:: ada

            Entity1   : Integer;
            My_Entity : Integer;

* Declarations should be grouped in a logical order.
  Related groups of declarations may be preceded by a header comment.

* All local subprograms in a subprogram or package body should be declared
  before the first local subprogram body.

* Do not declare local entities that hide global entities.

  .. index:: Hiding of outer entities

* Do not declare multiple variables in one declaration that spans lines.
  Start a new declaration on each line, instead.

* The defining_identifiers of global declarations serve as
  comments of a sort.  So don't choose terse names, but look for names
  that give useful information instead.

* Local names can be shorter, because they are used only within
  one context, where comments explain their purpose.

* When starting an initialization or default expression on the line that follows
  the declaration line, use 2 characters for indentation.

  .. code-block:: ada

            Entity1 : Integer :=
              Function_Name (Parameters, For_Call);

* If an initialization or default expression needs to be continued on subsequent
  lines, the continuations should be indented from the start of the expression.

  .. code-block:: ada

            Entity1 : Integer := Long_Function_Name
                                   (parameters for call);

Expressions and Names
---------------------

* Every operator must be surrounded by spaces. An exception is that
  this rule does not apply to the exponentiation operator, for which
  there are no specific layout rules. The reason for this exception
  is that sometimes it makes clearer reading to leave out the spaces
  around exponentiation.

  .. index:: Operators

  .. code-block:: ada

           E := A * B**2 + 3 * (C - D);

* Use parentheses where they clarify the intended association of operands
  with operators:

  .. index:: Parenthesization of expressions

  .. code-block:: ada

           (A / B) * C

Statements
----------

Simple and Compound Statements
******************************

* Use only one statement or label per line.

* A longer sequence_of_statements may be divided in logical
  groups or separated from surrounding code using a blank line.


If Statements
*************

* When the ``if``, ``elsif`` or ``else`` keywords fit on the
  same line with the condition and the ``then`` keyword, then the
  statement is formatted as follows:

  .. index:: Alignment (in an if statement)

  .. code-block:: ada

            if condition then
               ...
            elsif condition then
               ...
            else
               ...
            end if;

  When the above layout is not possible, ``then`` should be aligned
  with ``if``, and conditions should preferably be split before an
  ``and`` or ``or`` keyword a follows:

  .. code-block:: ada

            if long_condition_that_has_to_be_split
              and then continued_on_the_next_line
            then
               ...
            end if;

  The ``elsif``, ``else`` and ``end if`` always line up with
  the ``if`` keyword.  The preferred location for splitting the line
  is before ``and`` or ``or``.  The continuation of a condition is
  indented with two spaces or as many as needed to make nesting clear.
  As an exception, if conditions are closely related either of the
  following is allowed:

  .. code-block:: ada

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

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

* Conditions should use short-circuit forms ( ``and then``,
  ``or else`` ), except when the operands are boolean variables
  or boolean constants.

  .. index:: Short-circuit forms

* Complex conditions in ``if`` statements are indented two characters:

  .. index:: Indentation (in if statements)

  .. code-block:: ada

          if this_complex_condition
            and then that_other_one
            and then one_last_one
          then
             ...
          end if;

  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.

  .. code-block:: ada

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

* Every ``if`` block is preceded and followed by a blank line, except
  where it begins or ends a sequence_of_statements.

  .. index:: Blank lines (in an if statement)

  .. code-block:: ada

            A := 5;

            if A = 5 then
               null;
            end if;

            A := 6;

Case Statements
***************

* Layout is as below.  For long ``case`` statements, the extra indentation
  can be saved by aligning the ``when`` clauses with the opening ``case``.

  .. code-block:: ada

           case expression is
              when condition =>
                 ...
              when condition =>
                 ...
           end case;

Loop Statements
***************

* When possible, have ``for`` or ``while`` on one line with the
  condition and the ``loop`` keyword.

  .. code-block:: ada

           for J in S'Range loop
              ...
           end loop;

  If the condition is too long, split the condition (see 'If
  statements' above) and align ``loop`` with the ``for`` or
  ``while`` keyword.

  .. index:: Alignment (in a loop statement)

  .. code-block:: ada

          while long_condition_that_has_to_be_split
            and then continued_on_the_next_line
          loop
             ...
          end loop;

  If the loop_statement has an identifier, it is laid out as follows:

  .. code-block:: ada

          Outer : while not condition loop
             ...
          end Outer;

Block Statements
****************

* The ``declare`` (optional), ``begin`` and ``end`` words
  are aligned, except when the block_statement is named.  There
  is a blank line before the ``begin`` keyword:

  .. index:: Alignment (in a block statement)

  .. code-block:: ada

          Some_Block : declare
             ...

          begin
             ...
          end Some_Block;

Subprograms
-----------

Subprogram Declarations
***********************

* Do not write the ``in`` for parameters.

  .. code-block:: ada

          function Length (S : String) return Integer;

* 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:

  .. code-block:: ada

         procedure Set_Heading
           (Source : String;
            Count  : Natural;
            Pad    : Character := Space;
            Fill   : Boolean   := True);

  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:

  .. code-block:: ada

          function Head
            (Source : String;
             Count  : Natural;
             Pad    : Character := Space) return String;

  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:

  .. code-block:: ada

          function Head
            (Source : String;
             Count  : Natural;
             Pad    : Character := Space)
             return   String;

          function Head
            (Source : String;
             Count  : Natural;
             Pad    : Character := Space)
             return String;

Subprogram Bodies
*****************

* 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.

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

  .. code-block:: ada

          -----------------
          -- My_Function --
          -----------------

          procedure My_Function is
          begin
            ...
          end My_Function;

  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.

* Every subprogram body must have a preceding subprogram_declaration,
  which includes proper client documentation so that you do not need to
  read the subprogram body in order to understand what the subprogram does and
  how to call it. All subprograms should be documented, without exceptions.

  .. index:: 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.

* If the declarations in a subprogram contain at least one nested
  subprogram body, then just before the ``begin`` of the enclosing
  subprogram, there is a comment line and a blank line:

  .. code-block:: ada

        --  Start of processing for Enclosing_Subprogram

        begin
          ...
        end Enclosing_Subprogram;

* 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:

  .. code-block:: ada

        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;

        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;

  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.

Packages and Visibility Rules
-----------------------------

* All program units and subprograms have their name at the end:

  .. code-block:: ada

          package P is
             ...
          end P;

* We will use the style of ``use`` -ing ``with`` -ed packages, with
  the context clauses looking like:

  .. index:: use clauses

  .. code-block:: ada

          with A; use A;
          with B; use B;

* Names declared in the visible part of packages should be
  unique, to prevent name clashes when the packages are ``use`` d.

  .. index:: Name clash avoidance

  .. code-block:: ada

          package Entity is
             type Entity_Kind is ...;
             ...
          end Entity;

* After the file header comment, the context clause and unit specification
  should be the first thing in a program_unit.

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

  .. code-block:: ada

          package Preelaborate_Package is
             pragma Preelaborate;
             ...
          end Preelaborate_Package;

Program Structure and Compilation Issues
----------------------------------------

* Every GNAT source file must be compiled with the ``-gnatg``
  switch to check the coding style.
  (Note that you should look at
  style.adb to see the lexical rules enforced by ``-gnatg`` ).

  .. index:: -gnatg option (to gcc)
  .. index:: style.adb file

* Each source file should contain only one compilation unit.

* Filenames should be 8 or fewer characters, followed by the ``.adb``
  extension for a body or ``.ads`` for a spec.

  .. index:: File name length

* Unit names should be distinct when 'krunch'ed to 8 characters
  (see krunch.ads) and the filenames should match the unit name,
  except that they are all lower case.

  .. index:: krunch.ads file

.. toctree::
   share/gnu_free_documentation_license