Ada Style Guide/Source Code Presentation

Introduction
The physical layout of source text on the page or screen has a strong effect on its readability. This chapter contains source code presentation guidelines intended to make the code more readable.

In addition to the general purpose guidelines, specific recommendations are made in the "instantiation" sections. If you disagree with the specific recommendations, you may want to adopt your own set of conventions that still follow the general purpose guidelines. Above all, be consistent across your entire project.

An entirely consistent layout is hard to achieve or check manually. Therefore, you may prefer to automate layout with a tool for parameterized code formatting or incorporate the guidelines into an automatic coding template. Some of the guidelines and specific recommendations presented in this chapter cannot be enforced by a formatting tool because they are based on the semantics, not the syntax, of the Ada code. More details are given in the "automation notes" sections.

Code Formatting
The "code formatting" of Ada source code affects how the code looks, not what the code does. Topics included here are horizontal spacing, indentation, alignment, pagination, and line length. The most important guideline is to be consistent throughout the compilation unit as well as the project.

guideline

 * Use consistent spacing around delimiters.
 * Use the same spacing as you would in regular prose.

instantiation
Specifically, leave at least one blank space in the following places, as shown in the examples throughout this book. 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.

Do not leave any blank spaces in the following places, even if this conflicts with the above recommendations. When superfluous parentheses are omitted because of operator precedence rules, spaces may optionally be removed around the highest precedence operators in that expression.
 * After the plus (+) and minus (-) signs when used as unary operators.
 * After a function call.
 * Inside of label delimiters (<< >>).
 * Before and after the exponentiation operator (**), apostrophe ('), and period (.)
 * Between multiple consecutive opening or closing parentheses.
 * Before commas and semicolons.

rationale
It is a good idea to use white space around delimiters and operators because they are typically short sequences (one or two characters) that can easily get lost among the longer keywords and identifiers. Putting white space around them makes them stand out. Consistency in spacing also helps make the source code easier to scan visually.

However, many of the delimiters (commas, semicolons, parentheses, etc.) are familiar as normal punctuation marks. It is distracting to see them spaced differently in a computer program than in normal text. Therefore, use the same spacing as in text (no spaces before commas and semicolons, no spaces inside parentheses, etc.).

exceptions
The one notable exception is the colon. In Ada, it is useful to use the colon as a tabulator or a column separator (see Guideline 2.1.4). In this context, it makes sense to put spaces before and after the colon rather than only after it as in normal text.

automation notes
The guidelines in this section are easily enforced with an automatic code formatter.

guideline

 * Indent and align nested control structures, continuation lines, and embedded units consistently.
 * Distinguish between indentation for nested control structures and for continuation lines.
 * Use spaces for indentation, not the tab character (Nissen and Wallis 1984, §2.2).

instantiation
Specifically, the following indentation conventions are recommended, as shown in the examples throughout this book. Note that the minimum indentation is described. More spaces may be required for the vertical alignment recommended in subsequent guidelines.


 * Use the recommended paragraphing shown in the Ada Reference Manual (1995).
 * Use three spaces as the basic unit of indentation for nesting.
 * Use two spaces as the basic unit of indentation for continuation lines.

A label is outdented three spaces:

The if statement and the plain loop:

Loops with the for and while iteration schemes:

The block and the case statement as recommended in the Ada Reference Manual (1995):

These case statements save space over the Ada Reference Manual (1995) recommendation and depend on very short statement lists, respectively. Whichever you choose, be consistent:

The various forms of selective accept and the timed and conditional entry calls:

The accept statement:

A subunit:

Proper bodies of program units:

Context clauses on compilation units are arranged as a table. Generic formal parameters do not obscure the unit itself. Function, package, and task specifications use standard indentation:

Instantiations of generic units and record indentation:

Indentation for record alignment:

Tagged types and type extension:

rationale
Indentation improves the readability of the code because it gives you a visual indicator of the program structure. The levels of nesting are clearly identified by indentation, and the first and last keywords in a construct can be matched visually.

While there is much discussion on the number of spaces to indent, the reason for indentation is code clarity. The fact that the code is indented consistently is more important than the number of spaces used for indentation.

Additionally, the states that the layout shown in the examples and syntax rules in the manual is the recommended code layout to be used for Ada programs: "The syntax rules describing structured constructs are presented in a form that corresponds to the recommended paragraphing . . . . Different lines are used for parts of a syntax rule if the corresponding parts of the construct described by the rule are intended to be on different lines . . . . It is recommended that all indentation be by multiples of a basic step of indentation (the number of spaces for the basic step is not defined)."

It is important to indent continuation lines differently from nested control structures to make them visually distinct. This prevents them from obscuring the structure of the code as you scan it.

Listing context clauses on individual lines allows easier maintenance; changing a context clause is less error-prone.

Indenting with spaces is more portable than indenting with tabs because tab characters are displayed differently by different terminals and printers.

exceptions
If you are using a variable width font, tabs will align better than spaces. However, depending on your tab setting, lines of successive indentation may leave you with a very short line length.

automation notes
The guidelines in this section are easily enforced with an automatic code formatter.

guideline

 * Align operators vertically to emphasize local program structure and semantics.

rationale
Alignment makes it easier to see the position of the operators and, therefore, puts visual emphasis on what the code is doing.

The use of lines and spacing on long expressions can emphasize terms, precedence of operators, and other semantics. It can also leave room for highlighting comments within an expression.

exceptions
If vertical alignment of operators forces a statement to be broken over two lines, especially if the break is at an inappropriate spot, it may be preferable to relax the alignment guideline.

automation notes
The last example above shows a kind of "semantic alignment" that is not typically enforced or even preserved by automatic code formatters. If you break expressions into semantic parts and put each on a separate line, beware of using a code formatter later. It is likely to move the entire expression to a single line and accumulate all the comments at the end. However, there are some formatters that are intelligent enough to leave a line break intact when the line contains a comment. A good formatter will recognize that the last example above does not violate the guidelines and would, therefore, preserve it as written.

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 -- 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: Declarations of enumeration literals can be listed in one or more columns as: or, to save space:

or, to emphasize related groups of values:

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.

guideline

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

example
The following two examples show alternate instantiations of this guideline:

or:

Aligning parentheses makes complicated relational expressions more clear:

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

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

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.

guideline

 * Use blank lines to group logically related lines of text (NASA 1987).

example
This example separates different kinds of declarations with blank lines:

rationale
When blank lines are used in a thoughtful and consistent manner, sections of related code are more visible to readers.

automation notes
Automatic formatters do not enforce this guideline well because the decision on where to insert blank lines is a semantic one. However, many formatters have the ability to leave existing blank lines intact. Thus, you can manually insert the lines and not lose the effect when you run such a formatter.

guideline

 * Highlight the top of each package or task specification, the top of each program unit body, and the end statement of each program unit.

instantiation
Specifically, it is recommended that you:


 * Use file prologues, specification headers, and body headers to highlight those structures as recommended in Guideline 3.3.
 * Use a line of dashes, 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 immediately before and immediately after the definition.
 * If two dashed lines are adjacent, omit the longer of the two.

rationale
It is easy to overlook parts of program units that are not visible on the current page or screen. The page lengths of presentation hardware and software vary widely. By clearly marking the program's logical page boundaries (e.g., with a dashed line), you enable a reader to quickly check whether all of a program unit is visible. Such pagination also makes it easier to scan a large file quickly, looking for a particular program unit.

exceptions
This guideline does not address code layout on the physical "page" because the dimensions of such pages vary widely and no single guideline is appropriate.

automation notes
The guidelines in this section are easily enforced with an automatic code formatter.

guideline

 * Start each statement on a new line.
 * Write no more than one simple statement per line.
 * Break compound statements over multiple lines.

example
Use:

rather than:

exceptional case:

rationale
A single statement on each line enhances the reader's ability to find statements and helps prevent statements being missed. Similarly, the structure of a compound statement is clearer when its parts are on separate lines.

exceptions
If a statement is longer than the remaining space on the line, continue it on the next line. This guideline includes declarations, context clauses, and subprogram parameters.

According to the, "The preferred places for other line breaks are after semicolons."

automation notes
The guidelines in this section are easily enforced with an automatic code formatter, with the single exception of the last example, which shows a semantic grouping of multiple statements onto a single line.

exceptions
The example of Put and New_Line statements shows a legitimate exception. This grouping of closely related statements on the same line makes the structural relationship between the groups clear.

guideline

 * Adhere to a maximum line length limit for source code (Nissen and Wallis 1984, §2.3).

instantiation
Specifically, it is recommended that you:


 * Limit source code line lengths to a maximum of 72 characters.

rationale
When Ada code is ported from one system to another, there may be restrictions on the record size of source line statements, possibly for one of the following reasons: some operating systems may not support variable length records for tape I/O, or some printers and terminals support an 80-character line width with no line-wrap. See further rationale in the note for Guideline 7.1.2.

Source code must sometimes be published for various reasons, and letter-size paper is not as forgiving as a computer listing in terms of the number of usable columns.

In addition, there are human limitations in the width of the field of view for understanding at the level required for reading source code. These limitations correspond roughly to the 70- to 80-column range.

exceptions
An alternate instantiation is to limit source code length to 79 characters. The 79-character limit differentiates the code from the FORTRAN 72-character limit. It also avoids problems with 80-character width terminals where the character in the last column may not print correctly.

automation notes
The guidelines in this section are easily enforced with an automatic code formatter.

code formatting

 * Use consistent spacing around delimiters.
 * Use the same spacing as you would in regular prose.
 * Indent and align nested control structures, continuation lines, and embedded units consistently.
 * Distinguish between indentation for nested control structures and for continuation lines.
 * Use spaces for indentation, not the tab character (Nissen and Wallis 1984, §2.2).
 * Align operators vertically to emphasize local program structure and semantics.
 * 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.
 * Align parameter modes and parentheses vertically.
 * Use blank lines to group logically related lines of text (NASA 1987).
 * Highlight the top of each package or task specification, the top of each program unit body, and the end statement of each program unit.
 * Start each statement on a new line.
 * Write no more than one simple statement per line.
 * Break compound statements over multiple lines.
 * Adhere to a maximum line length limit for source code (Nissen and Wallis 1984, §2.3).