Language Ref Manual references: 2.3 Identifiers, 4.1 Universal Expressions
In this section...
3.2.2 Type Names
3.2.3 Object Names
3.2.4 Program Unit Names
3.2.5 Constants and Named Numbers
|Summary of Guidelines from this section|
Left_Branchis sufficient to convey the full meaning given the context. However, use
Mathematical formulas are often given using single-letter names for variables.
Continue this convention for mathematical equations where it would recall the
formula; for example:
A*(X**2) + B*C.
Language Ref Manual references: 3.1 Declarations
type Day is (Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday); type Day_Of_Month is range 0 .. 31; type Month_Number is range 1 .. 12; type Historical_Year is range -6_000 .. 2_500; type Date is record Day : Day_Of_Month; Month : Month_Number; Year : Historical_Year; end record;
Day should be used in preference to
Historical_Year might appear to be specific, but it is actually
general, with the adjective, historical, describing the range constraint.
However, using the name of a type from the predefined packages is sure to confuse a programmer when that type appears somewhere without a package qualification.
Language Ref Manual references: 3.3 Types and Subtypes, 8.6 The Package Standard, 14.3.10 Specification of the Package Text_IO
Today : Day; Yesterday : Day; Retirement_Date : Date;
User_Is_Available : Boolean; -- predicate clause List_Is_Empty : Boolean; -- predicate clause Empty : Boolean; -- adjective Bright : Boolean; -- adjective
General nouns, rather that specific, are used for record components because a
record object's name will supply the context for understanding the component.
Thus, the following component is understood as "the year of retirement.":
Following conventions which relate object types and parts of speech makes code read more like text. For example, because of the names chosen, the following code segment needs no comments:
if List_Is_Empty then Number_Of_Elements := 0; else Number_Of_Elements := Length_Of_List; end if;
Language Ref Manual references: 3.2 Objects and Named Numbers, 3.5.3 Boolean Types
Sample procedure names:
procedure Get_Next_Token -- get is a transitive verb procedure Create -- create is a transitverb
Sample function names for boolean-valued functions:
function Is_Last_Item -- predicate clause function Is_Empty -- predicate clause
Sample function names for nonboolean-valued functions:
function Successor -- common noun function Length -- attribute function Top -- component
Sample package names:
package Terminal is -- common noun package Text_Utilities is -- common noun
Sample task names:
task Terminal_Resource_Manager is -- common noun that shows action
Below is a sample piece of code to show the clarity that results from using these conventions the parts-of-speech naming conventions.
Get_Next_Token(Current_Token); case Current_Token is when Identifier => Process_Identifier; when Numeric => Process_Numeric; end case; -- Current_Token if Is_Empty(Current_List) then Number_Of_Elements := 0; else Number_Of_Elements := Length(Current_List); end if;
When packages and their subprograms are named together, the resulting code is very descriptive.
if Stack.Is_Empty(Current_List) then Current_Token := Stack.Top(Current_List); end if;
Language Ref Manual references: 6.1 Subprogram Declarations, 6.5 Function Subprograms, 7.2 Package Specifications and Declarations, 9.1 Abort Statements, 9.5 Entries, Entry Calls, and Accept Statements, 12.1 Generic Declarations, 12.3 Generic Instantiation
3.141_592_653_589_793 -- literal Max : constant Integer := 65_535; -- constant Pi : constant := 3.141_592; -- named number PI / 2 -- static expression PI -- symbolic value
Pi as a named number allows it to be referenced symbolically in the
assignment statement below:
Area := Pi * Radius**2; -- if radius is known.
Area := 3.141_59 * Radius**2; -- Needs explanatory comment.
ASCII.Bel is more expressive than
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
A constant has a type. A named number can only be a universal type: universal integer or universal real. Strong typing is enforced for identifiers but not 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.
Linear 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.
Fahrenheit := 32.0 + (9.0 * Celsius) / 5.0;
Language Ref Manual references: 2.4 Numeric Literals, 2.5 Character Literals, 2.6 String Literals, 3.2 Objects and Named Numbers, 4.9 Static Expressions and Static Subtypes, A. Predefined Language Attributes