Ada '83 Quality and Style:

Guidelines for Professional Programmers

Copyright 1989, 1991,1992 Software Productivity Consortium, Inc., Herndon, Virginia.

CHAPTER 3: Readability

3.1 Spelling

Spelling conventions in source code include rules for capitalization, use of underscores, and use of abbreviations. If these conventions are followed consistently, the resulting code is clearer and more readable.

In this section...
3.1.1 Use of Underscores
3.1.2 Numbers
3.1.3 Capitalization
3.1.4 Abbreviations

Summary of Guidelines from this section

3.1.1 Use of Underscores

guideline

Use underscores to separate words in a compound name.

example

Miles_Per_Hour 
Entry_Value

rationale

When an identifier consists of more than one word, it is much easier to read if the words are separated by underscores. Indeed, there is precedent in English in which compound words are separated by a hyphen. In addition to promoting readability of the code, if underscores are used in names, a code formatter has more control over altering capitalization. See Guideline 3.1.3.

Language Ref Manual references: 2.3 Identifiers

3.1.2 Numbers

guideline

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.

instantiation

Decimal and octal numbers are grouped by threes beginning counting on either side of the radix point.
The E is always capitalized in scientific notation.
Use upper case for the alphabetic characters representing digits in bases above 10.
Hexadecimal numbers are grouped by fours beginning counting on either side of the radix point.

example

type Maximum_Samples     is range          1 ..  1_000_000; 
type Legal_Hex_Address   is range   16#0000# ..   16#FFFF#; 
type Legal_Octal_Address is range 8#000_000# .. 8#777_777#;

Avogadro_Number : constant := 6.022_169E+23;

To represent the number 1/3 as a constant, use
One_Third : constant := 1.0 / 3.0;

Avoid this use.
One_Third_As_Decimal_Approximation : constant := 0.333_333_333_333_33;

or
One_Third_Base_3 : constant := 3#0.1#; -- Yes, it really works!

rationale

Consistent use of upper case or lower case aids scanning for numbers. Underscores serve to group portions of numbers into familiar patterns. Consistency with common use in everyday contexts is a large part of readability.

note

If a rational fraction is represented in a base in which it has a terminating rather than repeating representation, as 3#0.1# does in the example above, it may have increased accuracy upon conversion to the machine base.

Language Ref Manual references: 2.4 Numeric Literals

3.1.3 Capitalization

guideline

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

instantiation

Use lower case 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 upper case for abbreviations and acronyms (see automation note).

example

...

type Second_Of_Day      is range 0 .. 86_400; 
type Noon_Relative_Time is (Before_Noon, After_Noon, High_Noon);

subtype Morning   is Second_Of_Day range 0 .. 86_400 / 2 - 1; 
subtype Afternoon is Second_Of_Day range Morning'Last + 2 .. 86_400;

...

Current_Time := Second_Of_Day(Calendar.Seconds(Calendar.Clock));

if Current_Time in Morning then 
   Time_Of_Day := Before_Noon; 
elsif Current_Time in Afternoon then 
   Time_Of_Day := After_Noon; 
else 
   Time_Of_Day := High_Noon; 
end if;

case Time_Of_Day is 
   when Before_Noon =>   Get_Ready_For_Lunch; 
   when High_Noon   =>   Eat_Lunch; 
   when After_Noon  =>   Get_To_Work; 
end case;

...

rationale

Visually distinguishing reserved words allows the reader to focus on program structure alone, if desired, and also aids scanning for particular identifiers.

The instantiation chosen here is meant to be more readable for the experienced Ada programmer, who does not need reserved words to leap off the page. Beginners to any language often find that reserved words should be emphasized to help them find the control structures more easily. Because of this, instructors in the classroom and books introducing the Ada language may want to consider an alternative instantiation. It should be instructive to note that the Ada Language Reference Manual chose to bold all reserved words. Upper case for reserved words may also be suitable.

note

In Section 2.1, Nissen and Wallis (1984) states that "The choice of case is highly debatable, and that chosen for the [Ada Language Reference Manual (Department of Defense 1983)] is not necessarily the best. The use of lower case for reserved words is often preferred, so that they do not stand out too much. However, lower case is generally easier to read than upper case; words can be distinguished by their overall shape, and can be found more quickly when scanning the text."

automation note

Ada names are not case sensitive. Therefore the names max_limit, MAX_LIMIT, and Max_Limit denote the same object or entity. A good code formatter should be able to automatically convert from one style to another as long as the words are delimited by underscores.

As recommended in Guideline 3.1.4, abbreviations should be project wide. An automated tool should allow a project to specify those abbreviations and format them accordingly.

Language Ref Manual references: 2.3 Identifiers, 2.9 Reserved Words

3.1.4 Abbreviations

guideline

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.

example

Use Time_Of_Receipt rather than Recd_Time or R_Time.

But in an application that commonly deals with message formats that meet military standards, DOD_STD_MSG_FMT is an acceptable abbreviation for:
Department_Of_Defense_Standard_Message_Format.

rationale

Many abbreviations are ambiguous or unintelligible unless taken in context. As an example, Temp could indicate either temporary or temperature. For this reason, you should choose abbreviations carefully when you use them. The rationale in Guideline 8.1.2 provides a more thorough discussion of how context should influence the use of abbreviations.

Since very long variable names can obscure the structure of the program, especially in deeply nested (indented) control structures, it is a good idea to try to keep identifiers short and meaningful. Use short unabbreviated names whenever possible. If there is no short word which will serve as an identifier, then a well known unambiguous abbreviation is the next best choice, especially if it comes from a list of standard abbreviations used throughout the project.

An abbreviated format for a fully qualified name can be established via the renames clause. This capability is useful when a very long, fully qualified name would otherwise occur many times in a localized section of code (see Guideline 5.7.2).

A list of accepted abbreviations for a project provides a standard context for using each abbreviation.

Language Ref Manual references: 2.3 Identifiers

Back to document index