guideline

Use vertical alignment to enhance the readability of declarations.

Provide, at most, one declaration per line.

Indent all declarations in a single declarative part at the same level.

instantiation

For declarations not separated by blank lines, follow these alignment rules:

- Align the colon delimiters.
- Align the := initialization delimiter.
- When trailing comments are used, align the comment delimiter.
- When the declaration overflows a line, break the line and add an indentation level for those lines that wrap. The preferred places to break, in order, are: (1) the comment delimiter; (2) the initialization delimiter; (3) the colon delimiter.
- For enumeration type declarations that do not fit on a single line, put each literal on a separate line, using the next level of indentation. When appropriate, semantically related literals can be arranged by row or column to form a table.

example

Variable and constant declarations can be laid out in a tabular format with columns separated by the symbols :, :=, and --

    Prompt_Column : constant        := 40;
    Question_Mark : constant String := " ? "; -- prompt on error input
    Prompt_String : constant String := " ==> ";

If this results in lines that are too long, they can be laid out with each part on a separate line with its unique indentation level:

    subtype User_Response_Text_Frame is String (1 .. 72);
    -- If the declaration needed a comment, it would fit here.
    Input_Line_Buffer : User_Response_Text_Frame
           := Prompt_String &
              String'(1 .. User_Response_Text_Frame'Length -
                           Prompt_String'Length => ' ');

Declarations of enumeration literals can be listed in one or more columns as:

  type Op_Codes_In_Column is
        (Push,
         Pop,
         Add,
         Subtract,
         Multiply,
         Divide,
         Subroutine_Call,
         Subroutine_Return,
         Branch,
         Branch_On_Zero,
         Branch_On_Negative);

or, to save space:

    type Op_Codes_Multiple_Columns is
          (Push,            Pop,                Add,
           Subtract,        Multiply,           Divide,
           Subroutine_Call, Subroutine_Return,  Branch,
           Branch_On_Zero,  Branch_On_Negative);

or, to emphasize related groups of values:

    type Op_Codes_In_Table is
          (Push,            Pop,
           Add,             Subtract,          Multiply,    Divide,
           Subroutine_Call, Subroutine_Return,
           Branch,          Branch_On_Zero,
    Branch_On_Negative);

rationale

Many programming standards documents require tabular repetition of names, types, initial values, and meaning in unit header comments. These comments are redundant and can become inconsistent with the code. Aligning the declarations themselves in tabular fashion (see the examples above) provides identical information to both compiler and reader; enforces, at most, one declaration per line; and eases maintenance by providing space for initializations and necessary comments. A tabular layout enhances readability, thus preventing names from "hiding" in a mass of declarations. This applies to all declarations: types, subtypes, objects, exceptions, named numbers, and so forth.

automation notes

Most of the guidelines in this section are easily enforced with an automatic code formatter. The one exception is the last enumerated type example, which is laid out in rows based on the semantics of the enumeration literals. An automatic code formatter will not be able to do this and will likely move the enumeration literals to different lines. However, tools that are checking only for violations of the guidelines should accept the tabular form of an enumeration type declaration.