Chapter 3: Readability - TOC

3.5 SUMMARY

spelling

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 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 all lowercase.

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.

To justify its use, an abbreviation must save many characters over the full word.

Use abbreviations that are well-accepted in the application domain.

Maintain a list of accepted abbreviations, and use only abbreviations on that list.

naming conventions

Choose names that are as self-documenting as possible.

Use a short synonym instead of an abbreviation.

Use names given by the application, but do not use obscure jargon.

Avoid using the same name to declare different kinds of identifiers.

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 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 a consistent naming convention for tagged types and associated packages.

Use action verbs for procedures and entries.

Use predicate clauses for Boolean functions.

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

Consider naming generic subprograms as if they were nongeneric subprograms.

Consider naming 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 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 represents.

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

comments

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

Omit comments that merely repeat the information in the name.

Include information on redispatching for tagged types in cases where you intend the specializations (i.e., derived types) to override these redispatching operations.

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.

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.

using types

Limit the range of scalar types as much as possible.

Seek information about possible values from the application.

Do not reuse any of the subtype names in package Standard.

Use subtype declarations to improve program readability (Booch 1987).
Use derived types and subtypes in concert.

Use enumeration types instead of numeric codes.

Only if absolutely necessary, use representation clauses to match requirements of external devices.