Ada '83 Quality and Style:

Guidelines for Professional Programmers

Copyright 1989, 1991,1992 Software Productivity Consortium, Inc., Herndon, Virginia.

CHAPTER 5: Programming Practices

5.2 Parameter Lists

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.

In this section...
5.2.1 Formal Parameters
5.2.2 Named Association
5.2.3 Default Parameters
5.2.4 Mode Indication

Summary of Guidelines from this section

5.2.1 Formal Parameters

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

5.2.2 Named Association

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

5.2.3 Default Parameters

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

5.2.4 Mode Indication

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