[Ada Information Clearinghouse]
Ada '83 Quality and Style:
Guidelines for Professional Programmers
CHAPTER 5: Programming Practices
A subprogram or entry parameter list is the interface to the abstraction
implemented by the subprogram or entry. It is important that it is clear and
that it is expressed in a consistent style. Careful decisions about formal
parameter naming and ordering can make the purpose of the subprogram easier to
understand which can make it easier to use.
guideline
- Name formal parameters descriptively to reduce the need for comments.
example
List_Manager.Insert (Element => New_Employee,
Into_List => Probationary_Employees,
At_Position => 1);
rationale
Following the variable naming guidelines (Guidelines
3.2.1 and
3.2.3) for formal
parameters can make calls to subprograms read more like regular prose, as
shown in the example above where no comments are necessary. Descriptive names
of this sort can also make the code in the body of the subprogram more clear.
Language Ref Manual references:
2.3 Identifiers,
2.7 Comments,
6.1 Subprogram Declarations,
9.5 Entries, Entry Calls, and Accept Statements
guideline
- Use named parameter association in calls of infrequently used
subprograms or entries with many formal parameters.
- Use named association when instantiating generics.
- Use named association for clarification when the actual parameter is
any literal or expression.
- Use named association when supplying a nondefault value to an optional parameter.
instantiation
- Use named parameter association in calls of subprograms or entries
called from less than five places in a single source file or with more than
two formal parameters.
example
Encode_Telemetry_Packet (Source => Power_Electronics,
Content => Temperature,
Value =>
Read_Temperature_Sensor(Power_Electronics),
Time => Current_Time,
Sequence => Next_Packet_ID,
Vehicle => This_Spacecraft,
Primary_Module => True);
rationale
Calls of infrequently used subprograms or entries with many formal parameters
can be difficult to understand without referring to the subprogram or entry
code. Named parameter association can make these calls more readable.
When the formal parameters have been named appropriately, it is easier to
determine exactly what purpose the subprogram serves without looking at its
code. This reduces the need for named constants that exist solely to make
calls more readable. It also allows variables used as actual parameters to be
given names indicating what they are without regard to why they are being
passed in a call. An actual parameter, which is an expression rather than a
variable, cannot be named otherwise.
Named association allows subprograms to have new parameters inserted with
minimal ramifications to existing calls.
note
The judgment of when named parameter association improves readability is
subjective. Certainly, simple or familiar subprograms such as a swap routine
or a sine function do not require the extra clarification of named association
in the procedure call.
caution
A consequence of named parameter association is that the formal parameter
names may not be changed without modifying the text of each call.
Language Ref Manual references:
6.4 Subprogram Calls,
6.4.1 Parameter Associations,
6.4.2 Default Parameters,
12.3 Generic Instantiation
guideline
- Provide default parameters to allow for occasional, special use of
widely used subprograms or entries.
- Place default parameters at the end of the formal parameter list.
- Consider providing default values to new parameters added to an
existing subprogram.
example
Chapter 14 of the
Ada Language Reference Manual (Department of Defense 1983)
contains many examples of this practice.
rationale
Often, the majority of uses of a subprogram or entry need the same value for a
given parameter. Providing that value, as the default for the parameter, makes
the parameter optional on the majority of calls. It also allows the remaining
calls to customize the subprogram or entry by providing different values for
that parameter.
Placing default parameters at the end of the formal parameter list allows the
caller to use positional association on the call, otherwise defaults are
available only when named association is used.
Often during maintenance activities, you increase the functionality of a
subprogram or entry. This requires more parameters than the original form for
some calls. New parameters may be required to control this new functionality.
Give the new parameters default values which specify the old functionality.
Calls needing the old functionality need not be changed; they take the
defaults. This is true if the new parameters are added to the end of the
parameter list, or if named association is used on all calls. New calls
needing the new functionality can specify that by providing other values for
the new parameters.
This enhances maintainability in that the places which use the modified
routines do not themselves have to be modified, while the previous
functionality levels of the routines are allowed to be "reused."
exceptions
Do not go overboard. If the changes in functionality are truly radical, you
should be preparing a separate routine rather than modifying an existing one.
One indicator of this situation would be that it is difficult to determine
value combinations for the defaults that uniquely and naturally require the
more restrictive of the two functions. In such cases, it is better to go ahead
with creation of a separate routine.
Language Ref Manual references:
6.4.2 Default Parameters
guideline
- Show the mode indication of all procedure and entry parameters (Nissen
and Wallis 1984).
- Use
in out only when the parameter is both read from and updated.
example
procedure Open_File (File_Name : in String;
Open_Status : out Status_Codes);
entry Acquire (Key : in Capability;
Resource : out Tape_Drive);
rationale
By showing the mode of parameters, you aid the reader. If you do not specify a
parameter mode, the default mode is in. Explicitly showing the mode indication
of all parameters is a more assertive action than simply taking the default
mode. Anyone reviewing the code later will be more confident that you intended
the parameter mode to be in.
Use the mode that reflects the actual use of the parameter. Only use
in out mode when reading and writing to a parameter.
exception
It may be necessary to consider several alternative implementations for a
given abstraction. For example, a bounded stack can be implemented as a
pointer to an array. Even though an update to the object being pointed to
does not require changing the pointer value itself, you may want to consider
making the mode
in out to allow changes to the implementation and to document
more accurately what the operation is doing. If you later change the
implementation to a simple array, the mode will have to be
in out, potentially
causing changes to all places that the routine is called.
Language Ref Manual references:
6.2 Formal Parameter Modes,
9.5 Entries, Entry Calls, and Accept Statements
Back to document index