Ada Style Guide

For Internal Documentation

1.Introduction

This document offers a uniform style for creating Ada source code and documentation, and is intended as a guide for all programming assignments. Adherence to a consistent programming style is beneficial in:

Equivalent document: Java Style Guide , describes preferred coding style in terms of the language constructs of Java. The Java Style Guide essentially reuses the Ada Style Guide, translating Ada language references into Java.

2. Program structure and units

  1. A main program is organized as a series of subprogram calls, so that it operates at a higher level of abstraction than the subprograms.
  2. Only data that is necessary for the intercommunication of modules should be declared in the main program. All data should be declared as locally as possible to its usage.
  3. The definition of a subprogram should, in general, be given in two parts: a specification, defining the unit's interface, and a body defining its implementaiton. Most program units should fit on a single (printed) page.
  4. Each unit should have a single entrance and return statement, except for code specifically written for exception handling.
  5. Program units should communicate through parameter passing, not through global variables.

3. Identifiers

  1. Literals (digit strings representing numbers or character strings) should not be "hard coded"; they should be represented by constants instead. Constant names should contain upper case letters, digits and the underscore character only. Examples:
    2.     	   PI   : constant := 3.14159;
          STAR : constant := '*';
  2. Use all lower case for reserved word identifiers. Example:
    3.          procedure Header is
  3. Use all upper case for type and subtype identifiers. Example:
    4.          type STACK is array (1 .. MAX) of INTEGER;
  4. Every word in a variable identifier or procedure or function name should begin with a capital letter; the remaining letters should be lower case. Variable names should be nouns. Procedure or function names should be nouns or verbs, depending on their effect. Example:
    5.          Initial_Character: CHARACTER;
         procedure Stack_Initialization (S : out STACK);
         function StepOutside return ELEMENT;
         function IsEmpty (S: in STACK) return BOOEAN;
  5. Identifiers should be chosen to be descriptive and intuitive for an outsider reading the code, rather than just a convenient mnemonic shorthand for the author. Example:
    6.         TopLeftCorner
    rather than 
         xy0

4. Indentation, Alignment and Spacing

  1. Consistent indentation should be maintained throughout, using a fixed number of spaces to indent each successive level of nesting within the program. The TAB character may be put to good use instead of spaces, especially if the logic is not deeply nested. Example:
    2.         if (CountInstalled < ALLPIECES) then
                NextSquarePeg := SquarePeg;
                while BoardArray (NextSquarePeg) >  0 loop
                        Increment (NextSquarePeg);
                end loop;
                SolvePuzzle(NextSquarePeg, RoundHole);
        end if;
  2. Loop control statements and test statements should appear in their own line, above the statements they control. Example:
    3.         if OverTheSpeedLimit then
                EaseOffGas;
        elsif (Road = GardenStateParkway)
                while Speed < MINIMUM_SPEED loop
                      StepOnGas;
                end loop;
        end if;
    rather than 
            if OverTheSpeedLimit then EaseOffGas;
        elsif Road = GardenStateParkway
            while (Speed < MINIMUM_SPEED) loop StepOnGas end loop;
  3. Each statement should be on a separate line. Example:
    4.         Array_Index := 0;
        Flag := FALSE;

    rather than

            Array_Index := 0; Flag := FALSE;
  4. Each variable declaration should, in general, be on a separate line, with comments aligned on the right. (See section 5). 
            ALLPIECES : constant := 16;                -- checkers constant
        MyBoardCanvas : BOARD_CANVAS;             -- board display class
        SquareClicked : MOVE_RANGE;               -- where to move next
        OneStepOnly   : BOOLEAN;                  -- no jump possible
  5. Binary operators should be surrounded by blanks. Unary operators should directly precede their operands. Examples:
    6.         NetPay := GrossPay - StateTax - FederalTax;
        AmountOwed := -TotalDebits;
  6. Each condition of an if ... elsif ... else ... test sequence, as well as all "when" labels of a "case" statement, should be at the same level of indentation. Example:
    7.         if OneStepOnly
                OneStepOnly := FALSE;
        elsif (ThisOneIsDown (Piece(P,0) = FALSE) then 
                ThisOneIsDown (Piece (P,0)):= TRUE;
                Increment (CountInstalled);
        else 
                StepButton.Enable;
                GoButton.Enable;
                PauseButton.Disable;
        end if;
  7. In a record definition, the term record should appear on the same line as the type definition. Example: 
    8.             type STACK is record
    Of the two Lilliputian factions -- one camp putting the record at the end of the header line before a new text block, the other camp putting the term indented in the line below -- the author of this Guide sides with the former. More to the point, one should make a choice and then use the chosen style consistently.

5. Comments

  1. Comments improve comprehension throughout a program. Comments should be added to describe relatively long sets of related statements, algorithms that are not completely obvious, and any logical structure or group of statements that require special attention.
  2. In-line comments, to the right of a list of declarations, should line up.
  3. Terminating statements should each be followed by an in-line comment denoting the text block that they terminate. Example:
    4.        function Run (Color : in COLOR_TYPE;  
                     Board : in GRID) return RANGE_TYPE is 
            Position: RANGE_TYPE;
       begin
            SetBackground(Color.blue);
            loop
                    for Position in Board'Range (1) loop
                                . . .
                                
                                . . .
                    end loop;               -- end of for-loop
                        . . .
             end loop;                      -- end of infinite while
             return Position;
       end Run;
  4. Debug statements may be left in code to assist future software maintenance, by the simple expedient of commenting out the debug statements before releasing the software.
  5. Each file should each have a relatively verbose comment at its beginning serving as documentation at several levels. Example:
    6. 
-- FILE: 

    --    spider.ads

    --    specification for an Ada program using the GNAT compiler

    -- AUTHOR:  

    --    Michael B. Feldman, The George Washington University (Ada 95)

    -- MODIFIED BY: 

    --    Istvan Mohos to provide additional capabilities

    -- DATE : 

    --    November 1, 1996

    -- PURPOSE: 

    --    Provides an implementation of a spider walking on a board

    -- INCLUDES: 

    --    screen.ads

    -- INPUTS: 

    --    User inputs of moves for spider

    -- OUTPUTS:

    --    A board, with spider movements corresponding to user inputs

    -- NOTE:

    --    A movement off the edge of the board is treated as a wraparound

    -- ERROR CONDITIONS

    --   Incorrect user input is handled with an exception that prompts  

    --   users for correct input.