Bauhaus Coding Style Guide - DRAFT

see: file:/export/www/ada-doc/style_guide/contents.html (refered to as Ada QSG (Ada Quality and Style Guide)).

Exceptions to the rules mentioned there are shown in bold italics.

Chapter 2: Source Code Presentation

2.1. Code Formatting

2.1.1. Horizontal Spacing

Leave at least one blank space in the following places. More spaces may be required for the vertical alignment recommended in subsequent guidelines.

  • Before and after the following delimiters and binary operators: + - * / & < = > /= <= >= := => | .. : <>
  • Outside of the quotes for string (") and character (' ) literals, except where prohibited.
  • Outside, but not inside, parentheses.
  • After commas (,) and semicolons (;).
  • After a function's name in a function call. (exception to the rule in the Ada QSG!)

 

Do not leave any blank spaces in the following places, even if this conflicts with the above recommendations.

  • After the plus (+) and minus (-) signs when used as unary operators.
  • Before and after the exponentiation operator (**), apostrophe ('), and period (.)
  • Between multiple consecutive opening or closing parentheses.
  • Before commas (,) and semicolons (;).

2.1.2. Indentation

Use emacs Ada-mode for indentation of source lines.

Use emacs C-C C-F for formatting parameter lists.

For layout ref. to Ada QSG!

2.1.5 More on Alignment

Procedure/Function Call:

Use named parameter style in procedure/function calls.

If the call exceeds one line:

  • Place one actual parameter per line.
  • Begin a new line after the function name so taht opening bracket is on the new line.

2.1.7 Pagination

  • Use a line of dashes (to a total of 80 chars per line), beginning at the same column as the current indentation to highlight the definition of nested units embedded in a declarative part.
  • Insert the line of dashes in the package body between two definitions (with one empty line in front of and behind the dashed line)
  • Insert the line of dashes in the package specification to group definitions belonging together.
  • It is recommended that you describe the purpose of the following group between two dashed lines
  • Example:
 
    -- --------------------------------------------...
    -- Checks for membership
    --
    -- Reference: see page 78 of the design manual for further information
    -- --------------------------------------------...

    function Is_In_Rfg
      (The_Rfg  : in Rfg;
       The_Node :    Node_Ptr)
       return Boolean;
    -- Checks if 'The_Node' is included in 'The_Rfg'
    -- Status:  tested
    -- Precond: Init('The_RFG'), 'The_Node' != null
    -- Postcond: true

    function Is_In_Rfg
      (The_Rfg  : in Rfg;
       The_Edge :    Edge_Ptr)
       return Boolean;
    -- Checks if 'The_Edge' is included in 'The_Rfg'
    -- Status: tested
    -- Precond: Init('The_RFG'), 'The_Edge' != null
    -- Postcond: true

2.1.8. Number of Statements Per Line

Start each statement on a new line.

Write no more than one simple statement per line.

Break compound statements over multiple lines.

2.1.9 Source Code Line Length

Limit source code line lengths to a maximum of 80 characters.

Chapter 3: Readability

3.1. Spelling

3.1.1 Use of Underscores

Use underscores to separate words in a compound name.

3.1.3 Capitalization

Make reserved words and other elements of the program visually distinct from each other.

  • Use lowercase for all reserved words (when used as reserved words).
  • Use mixed case for all other identifiers, a capital letter beginning every word separated by underscores.
  • Use uppercase for abbreviations and acronyms.
  • Don't use capital letters for separating words in a compound word!

Use emacs Ada-mode default capitalization!

3.2 Naming Conventions

3.2.4 Naming of Tagged Types and Associated Packages

Use the name of the type declared within the file suffixed by "s" as name for the file (even if the word does not make sense like in Indexs):

 
package Nodes is
  type Node is ... end record;
end Nodes;

Try to keep every type in a different file!

3.3 Comments

  • Write comments behind the section of program you are referring to if the section is short (a declaration header or one statement)!
  • Write comments for larger sections of a program (groups of declarations, loops, sequences) in front of this section.
  • Try to avoid comments at the end of a non-empty line.
  • Example:
 
    -- computes the X-factor
    -- Note: loop necessary due to repeat-until structure of the problem

    loop

       X_Factor := Sci_Fi + 500;
       -- take galactic drift into account (refering to the previous line!)
       X_Factor := X_Factor * Beam_Constant;
       -- effect of Beam's constant
       exit when Finished (X_Factor);

    end loop;
  • If you refer to an identifier, enclose it in single quotes (e.g. 'The_Rfg')

3.3.2 File Headers

Use standard file headers provided in bauhaus/Ada-Code/doc/standard_header_ad[bs].

3.3.3 Program Unit Specification Headers

  • Put a header on the specification of each program unit.
  • Place information required by the user of the program unit in the specification header.
  • Do not repeat information (except unit name) in the specification header that is present in the specification (you may repeat the parameters' names int the explanation to describe which parameter serves for which purpose and within the Precond/Postcond/Raises section).
  • Explain what the unit does, not how or why it does it. Place this information in the body comment!
  • Describe the complete interface to the program unit, including any exceptions it can raise and any global effects it can have.
  • Do not include information about how the unit fits into the enclosing software system (e.g. the users of this unit).
  • Example:
 
    function Is_In_Rfg
      (The_Rfg  : in Rfg;
       The_Node :    Node_Ptr)
       return Boolean;
    -- Checks if 'The_Edge' is included in 'The_Rfg'
    -- Status: tested
    -- Precond: Init('The_RFG'), 'The_Edge' != null
    -- Postcond: true
    -- Raises: 'Not_In_Rfg' iff 'The_Edge' = null
    -- Effects: Increments 'Calls_So_Far' by one.
    -- Notes: This is a very long notice on the specialities of this very
    --        important function 'Is_In_Rfg' to show how the text in a very 
    --        verbose description is formatted!
  • You may omit sections you do not need. If you omit a section, this must by interpretable as follows:
 
    -- <you may never omit the purpose description!>
    -- Status: tested
    -- Precond: false
    -- Postcond: true
    -- Raises: nothing
    -- Effects: no effects on global state
    -- Notes: assume the worst!

3.3.4 Program Unit Body Headers

  • Place information required by the maintainer of the program unit in the body of the header
  • Explain how and why the unit performs its function, not what the unit does.
  • Do not repeat information (except unit name) in the header that is readily apparent from reading the code.
  • Do not repeat information (except unit name) in the body header that is available in the specification header.
  • Example:
 
    function Is_In_Rfg
      (The_Rfg  : in Rfg;
       The_Node :    Node_Ptr)
       return Boolean is
    -- Checks if 'The_Node's 'RFG_Pointer' equals 'The_RFG'
    -- Notes: This is a very long notice on the implementation specialities 
    --        of this very important function 'Is_In_Rfg' to show how the
    --        text in a very verbose description is formatted!
    -- Caution: Modifies global state!
  • You may omit sections you do not need.

5 Programming Practices

5.7 Visibility

5.7.1 The Use Clause

  • When you need to provide visibility to operators, use the use type clause.
  • Avoid the use of the use clause.
  • Consider using a "package renames" clause rather than a use clause for a package.
  • You have to fully qualify each name!