Essential Design Idioms for Packages

Motivation

Packages, especially library packages, are modules, and as such they are the fundamental building blocks of Ada programs. There is no language-prescribed way to use packages when designing an application, the language just specifies what is legal. However, some legal approaches are more advisable than others.

In particular, packages should exhibit high cohesion and loose coupling [1]. Cohesion is the degree to which the declarations within a module are related to one another, in terms of the problem being solved. In short, unrelated entities should not be declared in the same module so that the reader can focus on one primary concept. Coupling is the degree to which a module depends upon other modules. Loose coupling enhances comprehension and maintenance because it allows the developer/reader to examine and modify the module in relative isolation. Coupling and cohesion are interrelated, in that higher cohesion tends to result in less coupling.

Solution

Three idioms for packages were envisioned when the language was first designed. They were introduced and described in detail by the Rationale document for the initial language design [2]. They were then further developed in Grady Booch's book Software Engineering with Ada [3], a foundational work on design with the (sequential part of the) language. Booch added a fourth idiom, the Abstract Data Machine, to the three described by the Rationale.

These four idioms have proven themselves capable of producing packages that exhibit high cohesion and loose coupling, resulting in more comprehensible and more maintainable source code.

These idioms pre-date later package facilities, such as private packages and hierarchical packages. Idioms for those packages will be described separately.

Although generic packages are not actually packages, their instantiations are packages so these design idioms apply to generic packages as well.

Because these are idioms for modules, they are differentiated by what the package declarations can contain. But as you will see, what they can contain is a reflection of the degree of information hiding applied.

Essential Idiom 1: Named Collection of Declarations

In the first idiom the package declaration can contain other declarations only for the following:

• Objects (constants and variables)

• Types

• Exceptions

The idea is to factor out the common content required by multiple clients. Declaring common content in one place and letting clients reference the one unit makes the most sense.

For example, the following package declares several physical constants used in a high-fidelity aircraft simulator. These constants are utilized throughout the simulator code, so they are declared in one place and then referenced as needed:

package Physical_Constants is
   Polar_Radius   : constant  := 20_856_010.51; --  feet
   Equatorial_Radius : constant  := 20_926_469.20; --  feet
   Earth_Diameter : constant  :=
     2.0 * ((Polar_Radius + Equatorial_Radius)/2.0);
   Gravity  : constant  := 32.1740_4855_6430_4; --  feet/second**2
   Sea_Level_Air_Density   : constant  := 0.002378; --  slugs/foot**3
   Altitude_Of_Tropopause  : constant  := 36089.0; --  feet
   Tropopause_Temperature  : constant  := -56.5; --  degrees-C
end Physical_Constants;

No information hiding is applied with this idiom.

Pros

Packages designed with this idiom will have high cohesion and low coupling.

The idiom also enhances maintainability because changes to the values, if necessary, need only be made in one place.

Cons

When a library package contains variable declarations, these variables comprise global data. In this sense global means potential visibility to multiple clients. Global data should be avoided by default, because the effects of changes are potentially pervasive, throughout the entire set of clients that have visibility to it. In effect the developer must understand everything before changing anything. The introduction of new bugs is a common result. But if, for some compelling reason, the design really called for global data, this idiom provides the way to declare it.

Essential Idiom 2: Groups of Related Program Units

In this idiom, the package can contain all of the declarations allowed by the first idiom, but will also contain declarations for operations, usually subprograms but other units are also allowed, e.g., protected types/objects. Hence:

• Objects (constants and variables)

• Types

• Exceptions

• Operations

The intent is that the types declared in the package are used by the operations, e.g., in the formal parameters and/or function return types. In particular, though, the types are not private types.

For example:

package Linear_Algebra is
   type Vector is array (Positive range <>) of Real;
   type Matrix is array (Positive range <>, Positive range <>) of Real;
   function "+" (Left, Right : Vector) return Vector;
   function "*" (Left, Right : Vector) return Matrix;
   -- ...
end Linear_Algebra;

In this code, Vector and Matrix are the types under consideration. The type Real might be declared here too, but it might be better declared in a Named Collection of Declarations package referenced in a with-clause. In any case this package declares types and subprograms that manipulate values of the types via parameters.

Variables might also be declared in the package, but not as the central purpose of the package. Perhaps we want to have a variable whose value is used as the default for some formal parameters. Clients can change the default for subsequent calls by first assigning a different value to the variable, unlike a hardcoded literal chosen by the developer. For example:

Default_Debounce_Time : Time_Span := Milliseconds (75);
--  The default amount of time used to debounce an input pin.
--  This value is tunable.

procedure Await_Active
  (This : Discrete_Input;
   Debounce_Time : Time_Span := Default_Debounce_Time);

With this idiom, information hiding applies to the implementations of the visible subprograms in the package body, as well as any internal entities declared in the body for the sake of implementing the visible subprograms.

As mentioned, these idioms apply to generic packages as well. For example, the more realistic approach would be to make type Real be a generic formal type:

generic
   type Real is digits <>;
package Linear_Algebra is
   type Vector is array (Positive range <>) of Real;
   type Matrix is array (Positive range <>, Positive range <>) of Real;
   function "+" (Left, Right : Vector) return Vector;
   function "*" (Left, Right : Vector) return Matrix;
   --  ...
end Linear_Algebra;

Pros

The types and the associated operations are grouped together, hence highly cohesive. Such packages usually can be loosely coupled as well.

Clients have all the language-defined operations available that the type representations provide. In the case of Vector and Matrix, clients have compile-time visibility to the fact they are array types. Therefore, clients can manipulate Vector and Matrix values as arrays: they can create values via aggregates, for example, and can use array indexing to get to specific components.

Cons

Clients can write code that depends on the type's representation, and can be relied upon to do so. Consequently, a change in the representation will potentially require redeveloping the client code, which could be extensive and expensive.

However, compile-time visibility to the type representations may be necessary to meet client expectations. For example, engineers expect to use indexing with vectors and matrices. Ada — by design — does not allow developers to redefine extremely low-level operations such as array indexing. Consequently, those types must be compile-time visible to clients as array types. We could define functions as alternatives to indexing and aggregates, but would clients accept that relatively heavy approach?

Notes

1. The rules for what these idiomatic packages contain are not meant to be iron-clad; hybrids are possible but should be considered initially suspect and reviewed accordingly.

Bibliography

[1]

Yourdon, E. and L. L. Constantine (1979). Structured Design: Fundamentals of a Discipline of Computer Program and System Design, Prentice-Hall.

[2]

Ichbiah, J., J. Barnes, et al. (1986). Rationale for the Design of the Ada Programming Language.

[3]

Booch, G. (1983). Software Engineering with Ada, Benjamin/Cummings Publishing Company.