Ada 95 Quality and Style Guide Chapter 3
This chapter recommends ways of using Ada features to make reading
and understanding code easier. There are many myths about comments
and readability. The responsibility for true readability rests
more with naming and code structure than with comments. Having
as many comment lines as code lines does not imply readability;
it more likely indicates the writer does not understand what is
important to communicate.
Spelling conventions in source code include rules for capitalization
and use of underscores, numbers, and abbreviations. If you follow
these conventions consistently, the resulting code is clearer
and more readable.
3.1.1 Use of Underscores
- Use underscores to separate words in a compound
- Represent numbers in a consistent fashion.
- Represent literals
in a radix appropriate to the problem.
- Use underscores to separate digits
the same way commas or periods (or spaces for nondecimal bases)
would be used in normal text.
- When using scientific notation, make
the E consistently either uppercase or lowercase.
- In an alternate base, represent the alphabetic characters in
either all uppercase or
- Decimal and octal numbers are grouped by threes beginning on
the left side of the radix point and by fives beginning on the
right side of the radix point.
- The E is always capitalized in scientific notation.
- Use uppercase for the alphabetic characters representing digits
in bases above 10.
- Hexadecimal numbers are grouped by fours beginning on either
side of the radix point.
- 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 (see automation notes).
- Do not use an abbreviation of a long word as an identifier
where a shorter synonym exists.
- Use a consistent abbreviation strategy.
- Do not use ambiguous abbreviations.
- To justify its use, an abbreviation must save many characters
over the full word.
- Use abbreviations that are well-accepted in the application
- Maintain a list of accepted abbreviations, and use only abbreviations
on that list.
3.2 NAMING CONVENTIONS
Choose names that clarify the object's or entity's intended use.
Ada allows identifiers to be any length as long as the identifier
fits on a line with all characters being significant (including
are the names used for variables, constants, program units, and
other entities within a program.
3.2.2 Subtype Names
- Choose names that are as self-documenting
- Use a short synonym instead of an abbreviation
(see Guideline 3.1.4).
- Use names given by the application, but do not use obscure jargon.
- Avoid using the same name to declare different kinds of identifiers.
3.2.3 Object Names
- Use singular, general nouns as subtype identifiers.
- Choose identifiers that describe one of the subtype's values.
- Consider using suffixes for subtype identifiers that define
visible access types, visible subranges, or visible array types.
- For private types, do not use identifier constructions (e.g.,
suffixes) that are unique to subtype identifiers.
- Do not use the subtype names from predefined
3.2.4 Naming of Tagged Types and Associated Packages
- Use predicate clauses or adjectives
for Boolean objects.
- Use singular, specific nouns as object
- Choose identifiers that describe the object's
value during execution.
- Use singular, general nouns as
identifiers for record components.
- Use a consistent naming convention for tagged types and associated
- Name tagged types no differently than subtype names (see Guideline
- Use the prefix Abstract_ for packages that export an
abstraction for which you intend to provide multiple implementations
(see Guideline 9.2.4).
- Use the suffix _Mixin for packages that provide units
of functionality that can be "mixed in" to core abstractions.
3.2.5 Program Unit Names
- Name class packages after the object they represent, without
a suffix (Rosen 1995).
- Name mixin packages after the facet they represent, appending
the suffix _Facet (Rosen 1995).
- Name the main tagged type Instance (Rosen 1995).
- Follow the declaration of the specific type with a subtype named
Class for the corresponding class-wide type (Rosen 1995).
3.2.6 Constants and Named Numbers
- Use action verbs
for procedures and entries.
- Use predicate clauses for Boolean
- Use nouns for non-Boolean functions.
- Give packages names that imply a higher level
of organization than subprograms. Generally, these are noun
phrases that describe the abstraction provided.
- Give tasks names that imply an active entity.
- Use nouns descriptive of the data being protected for protected
- Consider naming generic subprograms as if they were nongeneric
- Consider naming generic packages as if they were nongeneric
- Make the generic names more general than the
- Use symbolic values instead of literals,
- Use the predefined constants Ada.Numerics.Pi and Ada.Numerics.e
for the mathematical constants Pi and e.
- Use constants instead
of variables for constant values.
- Use a constant when the value is specific to a type or when
the value must be static.
- Use named numbers instead
of constants, whenever possible.
- Use named numbers to replace numeric literals whose type or
context is truly universal.
- Use constants for objects whose values cannot change after elaboration
(United Technologies 1987).
- Show relationships between symbolic values by defining them
with static expressions.
- Use linearly independent
sets of literals.
- Use attributes like 'First and 'Last instead
of literals, wherever possible.
- Use a name that indicates the kind of problem the exception
- Include a prefix like New, Make, or Create
in naming constructors (in this sense, operations to create and/or
initialize an object).
- Use names indicative of their content for child packages containing
- Name a child package containing constructors <whatever>.Constructor.
Comments in source text are a controversial issue. There are arguments
both for and against the view that comments enhance readability.
In practice, the biggest problem with comments is that people
often fail to update them when the associated source text is changed,
thereby making the commentary misleading. Commentary should be
reserved for expressing needed information that cannot be expressed
in code and highlighting cases where there are overriding reasons
to violate one of the guidelines. If possible, source text should
self-explanatory names for objects and program units, and it should
use simple, understandable program structures so that little additional
commentary is needed. The extra effort in selecting (and entering)
appropriate names and the extra thought needed to design clean
and understandable program structures are fully justified.
Use comments to state the intent of the code. Comments that provide
an overview of the code help the maintenance programmer see the
forest for the trees. The code itself is the detailed "how"
and should not be paraphrased in the comments.
Comments should be minimized. They should
provide needed information that cannot be expressed in the Ada
language, emphasize the structure of code, and draw attention
to deliberate and necessary violations
of the guidelines. Comments are present either to draw attention
to the real issue being exemplified or to compensate for incompleteness
in the sample program.
Maintenance programmers need to know the causal interaction of
noncontiguous pieces of code to get a global, more or less complete
sense of the program. They typically acquire this kind of information
from mental simulation of parts of the code. Comments should be
sufficient enough to support this process (Soloway et al. 1986).
This section presents general guidelines about how to write good
comments. It then defines several different classes of comments
with guidelines for the use of each. The classes are file headers,
program unit specification headers, program unit body headers,
data comments, statement comments, and marker comments.
3.3.1 General Comments
3.3.2 File Headers
- Make the code as clear as possible to reduce the need for comments.
- Never repeat information in a comment that is readily available
in the code.
- Where a comment is required, make it concise and complete.
- Use proper grammar and spelling in
- Make comments visually distinct from the code.
- Structure comments in headers so that information
can be automatically extracted by a tool.
- Put a file header on each source file.
- Place ownership, responsibility, and history information for
the file in the file header.
- Put a copyright notice in the file header.
- Put the author's name and department in the file header.
- Put a revision history in the file header, including a summary
of each change, the date, and the name of the person making the
Chapter 3 continued