Chapter 3: Readability - TOC - 3.2 NAMING CONVENTIONS

3.2.6 Constants and Named Numbers

guideline

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.

example

3.14159_26535_89793                                 -- literal
Max_Entries : constant Integer       := 400;        -- constant
Avogadros_Number  : constant := 6.022137 * 10**23;  -- named number
Avogadros_Number / 2                                -- static expression
Avogadros_Number                                    -- symbolic value

Declaring Pi as a named number (assuming a with clause for the predefined package Ada.Numerics in the Ada Reference Manual [1995, §A.5] allows it to be referenced symbolically in the assignment statement below:

Area :=       Pi * Radius**2;       -- if radius is known.

instead of:

Area := 3.14159 * Radius**2;        -- Needs explanatory comment.

Also, Ada.Characters.Latin_1.Bel is more expressive than Character'Val(8#007#).

Clarity of constant and named number declarations can be improved by using other constant and named numbers. For example:

Bytes_Per_Page   : constant := 512;
Pages_Per_Buffer : constant := 10;
Buffer_Size      : constant := Pages_Per_Buffer * Bytes_Per_Page;

is more self-explanatory and easier to maintain than:

Buffer_Size : constant := 5_120;   -- ten pages

The following literals should be constants:

if New_Character  = '$' then  -- "constant" that may change
...
if Current_Column = 7 then    -- "constant" that may change

rationale

Using identifiers instead of literals makes the purpose of expressions clear, reducing the need for comments. Constant declarations consisting of expressions of numeric literals are safer because they do not need to be computed by hand. They are also more enlightening than a single numeric literal because there is more opportunity for embedding explanatory names. Clarity of constant declarations can be improved further by using other related constants in static expressions defining new constants. This is not less efficient because static expressions of named numbers are computed at compile time.

A constant has a type. A named number can only be a universal type: universal_integer or universal_real. Strong typing is enforced for constants but not for named numbers or literals. Named numbers allow compilers to generate more efficient code than for constants and to perform more complete error checking at compile time. If the literal contains a large number of digits (as Pi in the example above), the use of an identifier reduces keystroke errors. If keystroke errors occur, they are easier to locate either by inspection or at compile time.

Independence of literals means that the few literals that are used do not depend on one another and that any relationship between constant or named values is shown in the static expressions. Linear independence of literal values gives the property that if one literal value changes, all of the named numbers of values dependent on that literal are automatically changed.

See Guideline 4.1.4 for additional guidelines on choosing a parameterless function versus a constant.

notes

There are some gray areas where the literal is actually more self-documenting than a name. These are application-specific and generally occur with universally familiar, unchangeable values such as the following relationship:

Fahrenheit := 32.0 + (9.0 * Celsius) / 5.0;