Ada '83 Quality and Style:
Guidelines for Professional Programmers
Copyright 1989, 1991,1992
Software Productivity Consortium, Inc., Herndon, Virginia.
CHAPTER 3: Readability
- Use underscores to separate words in a compound name.
- 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 handwritten text.
- When using scientific notation, make the
E
consistently either upper
or lower case.
- In an alternate base, represent the alphabetic characters in either
all upper case or all lower case.
- Make reserved words and other elements of the program visually
distinct from each other.
- 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.
- An abbreviation must save many characters over the full word to be
justified.
- Use abbreviations that are well-accepted in the application domain.
- Maintain a list of accepted abbreviations and use only abbreviations
on that list.
- Choose names that are as self-documenting as possible.
- Use a short synonym instead of an abbreviation (see Guideline 3.1.4).
- Use names given by the application but not obscure jargon.
- Use singular, general nouns as (sub)type identifiers.
- Choose identifiers that describe one of the (sub)type's values.
- Do not use identifier constructions (e.g., suffixes) that are unique
to (sub)type identifiers.
- Do not use the type names from predefined packages.
- Use predicate clauses or adjectives for boolean objects.
- Use singular, specific nouns as object identifiers.
- Choose identifiers that describe the object's value during execution.
- Use singular, general nouns as identifiers for record components.
- Use action verbs for procedures and entries.
- Use predicate-clauses for boolean functions.
- Use nouns for nonboolean functions.
- Give packages names that imply higher levels of organization than
subprograms. Generally, these are noun phrases that describe the abstraction
provided.
- Give tasks names that imply an active entity.
- Name generic subprograms as if they were nongeneric subprograms.
- Name generic packages as if they were nongeneric packages.
- Make the generic names more general than the instantiated names.
- Use symbolic values instead of literals wherever possible.
- Use constants instead of variables for constant values.
- Use named numbers instead of constants when 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.
- Make the code as clear as possible to reduce the need for comments.
- Never repeat information in a comment which is readily available in
the code.
- Where a comment is required, make it concise and complete.
- Use proper grammar and spelling in comments.
- 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 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 which is present in the specification.
- Explain what the unit does, not how or why it does it.
- 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.
- Describe the performance (time and space) characteristics of the unit.
- Place information required by the maintainer of the program unit in
the body 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.
- Comment on all data types, objects, and exceptions unless their names
are self-explanatory.
- Include information on the semantic structure of complex pointer-based data structures.
- Include information about relationships that are maintained between
data objects.
- Do not include comments that merely repeat the information in the name.
- Minimize comments embedded among statements.
- Use comments only to explain parts of the code that are not obvious.
- Comment intentional omissions from the code.
- Do not use comments to paraphrase the code.
- Do not use comments to explain remote pieces of code, such as
subprograms called by the current unit.
- Where comments are necessary, make them visually distinct from the
code.
- Use pagination markers to mark program unit boundaries (Guideline 2.1.7).
- Repeat the unit name in a comment to mark the begin of a package body,
subprogram body, task body, or block if the begin is preceded by declarations.
- For long or heavily nested if and case statements, mark the end of the
statement with a comment summarizing the condition governing the statement.
- For long or heavily nested if statements, mark the else part with a
comment summarizing the conditions governing this portion of the statement.
- Limit the range of scalar types as much as possible.
- Seek information about possible values from the application.
- Do not overload any of the type names in package Standard.
- Use subtype declarations to improve program readability (Booch 1987).
- Use derived types and subtypes in concert (see Guideline 5.3.1).
- Use enumeration types instead of numeric codes.
- Use representation clauses to match requirements of external devices.
Back to document index
This file was converted with TextToHTML - (c) Logic n.v.