Chapter 5: Programming Practices - TOC - 5.2 PARAMETER LISTS

5.2.4 Mode Indication

guideline

Show the mode indication of all procedure and entry parameters (Nissen and Wallis 1984).

Use the most restrictive parameter mode applicable to your application.

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. You should avoid the tendency to make all parameters in out mode because out mode parameters may be examined as well as updated.

exceptions

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.