Ada 95 Quality and Style Guide Chapter 2

Chapter 2: Source Code Presentation - TOC - 2.1 CODE FORMATTING

2.1.5 More on Alignment


  • Align parameter modes and parentheses vertically.
  • instantiation

    Specifically, it is recommended that you:

    - Place one formal parameter specification per line.
    - Vertically align parameter names, colons, the reserved word in, the reserved word out, and parameter subtypes.
    - Place the first parameter specification on the same line as the subprogram or entry name. If any parameter subtypes are forced beyond the line length limit, place the first parameter specification on a new line indented the same as a continuation line.


        procedure Display_Menu (Title   : in     String;
                                Options : in     Menus;
                                Choice  :    out Alpha_Numerics);

    The following two examples show alternate instantiations of this guideline:

    procedure Display_Menu_On_Primary_Window (Title : in String; Options : in Menus; Choice : out Alpha_Numerics);


        procedure Display_Menu_On_Screen (
              Title   : in     String;
              Options : in     Menus;
              Choice  :    out Alpha_Numerics

    Aligning parentheses makes complicated relational expressions more clear:

        if not (First_Character in Alpha_Numerics and then
                Valid_Option(First_Character))        then


    This alignment facilitates readability and understandability, and it is easy to achieve given automated support. Aligning parameter modes provides the effect of a table with columns for parameter name, mode, subtype, and, if necessary, parameter-specific comments. Vertical alignment of parameters across subprograms within a compilation unit increases the readability even more.


    Various options are available for subprogram layout. The second example above aligns all of the subprogram names and parameter names in a program. This has the disadvantage of occupying an unnecessary line where subprogram names are short and looking awkward if there is only one parameter.

    The third example is a format commonly used to reduce the amount of editing required when parameter lines are added, deleted, or reordered. The parentheses do not have to be moved from line to line. However, the last parameter line is the only one without a semicolon.


    When an operator function has two or more formal parameters of the same type, it is more readable to declare the parameters in a single one-line list rather than to separate the formal parameter list into multiple formal parameter specifications.

         type Color_Scheme is (Red, Purple, Blue, Green, Yellow, White, Black, 
                 Brown, Gray, Pink); 
        function "&" (Left, Right : Color_Scheme) return Color_Scheme;

    automation notes

    Most of the guidelines in this section are easily enforced with an automatic code formatter. The one exception is the last example, which shows vertical alignment of parentheses to emphasize terms of an expression. This is difficult to achieve with an automatic code formatter unless the relevant terms of the expression can be determined strictly through operator precedence.

    < Previous Page Search Contents Index Next Page >
    1 2 3 4 5 6 7 8 9 10 11
    Appendix References Bibliography