Skip to main content

3.1 Spelling

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.

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 or a space. 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.

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

instantiation​

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

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.02216_9E+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.33333_33333_3333;

or:

One_Third_Base_3 : constant := 3#0.1#;

rationale​

Consistent use of uppercase or lowercase 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.

notes​

If a rational fraction is represented in a base in which it has a terminating rather than a repeating representation, as 3#0.1# does in the example above, it may have increased accuracy upon conversion to the machine base. (This is wrong for named numbers as in this example - they must be calculated exactly.)

Capitalization​

guideline​

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

instantiation​

  • 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).

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 you 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. The Ada Reference Manual (1995) chose bold lowercase for all reserved words.

automation notes​

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.

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

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.

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

You can establish an abbreviated format for a fully qualified name using 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.