Chapter 5: Programming Practices - TOC - 5.7 VISIBILITY

5.7.1 The Use Clause

guideline

When you need to provide visibility to operators, use the use type clause.

Avoid/minimize the use of the use clause (Nissen and Wallis 1984).

Consider using a package renames clause rather than a use clause for a package.

Consider using the use clause in the following situations:

- When standard packages are needed and no ambiguous references are introduced

- When references to enumeration literals are needed

Localize the effect of all use clauses.

example

This is a modification of the example from Guideline 4.2.3. The effect of a use clause is localized:

----------------------------------------------------------------------------------
package Rational_Numbers is
   type Rational is private;
   function "=" (X, Y : Rational) return Boolean;
   function "/" (X, Y : Integer)  return Rational;  -- construct a rational number
   function "+" (X, Y : Rational) return Rational;
   function "-" (X, Y : Rational) return Rational;
   function "*" (X, Y : Rational) return Rational;
   function "/" (X, Y : Rational) return Rational;  -- rational division
private
   ...
end Rational_Numbers;
----------------------------------------------------------------------------------
package body Rational_Numbers is
   procedure Reduce (R : in out Rational) is . . . end Reduce;
   . . .
end Rational_Numbers;
----------------------------------------------------------------------------------
package Rational_Numbers.IO is
   ...

   procedure Put (R : in  Rational);
   procedure Get (R : out Rational);
end Rational_Numbers.IO;
----------------------------------------------------------------------------------
with Rational_Numbers;
with Rational_Numbers.IO;
with Ada.Text_IO;
procedure Demo_Rationals is
   package R_IO renames Rational_Numbers.IO;

   use type Rational_Numbers.Rational;
   use R_IO;
   use Ada.Text_IO;

   X : Rational_Numbers.Rational;
   Y : Rational_Numbers.Rational;
begin  -- Demo_Rationals
   Put ("Please input two rational numbers: ");
   Get (X);
   Skip_Line;
   Get (Y);
   Skip_Line;
   Put ("X / Y = ");
   Put (X / Y);
   New_Line;
   Put ("X * Y = ");
   Put (X * Y);
   New_Line;
   Put ("X + Y = ");
   Put (X + Y);
   New_Line;
   Put ("X - Y = ");
   Put (X - Y);
   New_Line;
end Demo_Rationals;

rationale

These guidelines allow you to maintain a careful balance between maintainability and readability. Use of the use clause may indeed make the code read more like prose text. However, the maintainer may also need to resolve references and identify ambiguous operations. In the absence of tools to resolve these references and identify the impact of changing use clauses, fully qualified names are the best alternative.

Avoiding the use clause forces you to use fully qualified names. In large systems, there may be many library units named in with clauses. When corresponding use clauses accompany the with clauses and the simple names of the library packages are omitted (as is allowed by the use clause), references to external entities are obscured and identification of external dependencies becomes difficult.

In some situations, the benefits of the use clause are clear. A standard package can be used with the obvious assumption that the reader is very familiar with those packages and that additional overloading will not be introduced.

The use type clause makes both infix and prefix operators visible without the need for renames clauses. You enhance readability with the use type clause because you can write statements using the more natural infix notation for operators. See also Guideline 5.7.2.

You can minimize the scope of the use clause by placing it in the body of a package or subprogram or by encapsulating it in a block to restrict visibility.

notes

Avoiding the use clause completely can cause problems with enumeration literals, which must then be fully qualified. This problem can be solved by declaring constants with the enumeration literals as their values, except that such constants cannot be overloaded like enumeration literals.

An argument defending the use clause can be found in Rosen (1987).

automation notes

There are tools that can analyze your Ada source code, resolve overloading of names, and automatically convert between the use clause or fully qualified names.