|Ada 95 Quality and Style Guide||Chapter 3|
3.2.5 Program Unit Names
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.
The following are sample names for elements that compose an Ada program:
Sample procedure names:procedure Get_Next_Token -- get is a transitive verb procedure Create -- create is a transitive verb
Sample function names for Boolean-valued functions:function Is_Last_Item -- predicate clause function Is_Empty -- predicate clause
Sample function names for non-Boolean-valued functions:function Successor -- common noun function Length -- attribute function Top -- component
Sample package names:package Terminals is -- common noun package Text_Routines is -- common noun
Sample protected objects:protected Current_Location is -- data being protected protected type Guardian is -- noun implying protection
Sample task names:task Terminal_Resource_Manager is -- common noun that shows action
The following sample piece of code shows the clarity that results from using 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;
Using these naming conventions creates understandable code that reads much like natural language. When verbs are used for actions, such as subprograms, and nouns are used for objects, such as the data that the subprogram manipulates, code is easier to read and understand. This models a medium of communication already familiar to a reader. Where the pieces of a program model a real-life situation, using these conventions reduces the number of translation steps involved in reading and understanding the program. In a sense, your choice of names reflects the level of abstraction from computer hardware toward application requirements.
See also Guideline 3.2.4 for the use of special-purpose suffixes in packages associated with tagged types.
There are some conflicting conventions in current use for task entries. Some programmers and designers advocate naming task entries with the same conventions used for subprograms to blur the fact that a task is involved. Their reasoning is that if the task is reimplemented as a package, or vice versa, the names need not change. Others prefer to make the fact of a task entry as explicit as possible to ensure that the existence of a task with its presumed overhead is recognizable. Project-specific priorities may be useful in choosing between these conventions.
|< Previous Page||Search||Contents||Index||Next Page >|