Chapter 5: Programming Practices - TOC - 5.7 VISIBILITY

5.7.2 The Renames Clause

guideline

Limit the scope of a renaming declaration to the minimum necessary scope.

Rename a long, fully qualified name to reduce the complexity if it becomes unwieldy (see Guideline 3.1.4).

Use renaming to provide the body of a subprogram if this subprogram merely calls the first subprogram.

Rename declarations for visibility purposes rather than using the use clause, except for operators (see Guideline 5.7.1).

Rename parts when your code interfaces to reusable components originally written with nondescriptive or inapplicable nomenclature.

Use a project-wide standard list of abbreviations to rename common packages.

Provide a use type rather than a renames clause to provide visibility to operators.

example

procedure Disk_Write (Track_Name : in     Track;
                      Item       : in     Data) renames
   System_Specific.Device_Drivers.Disk_Head_Scheduler.Transmit;

See also the example in Guideline 5.7.1, where a package-level renames clause provides an abbreviation for the package Rational_Numbers_IO.

rationale

If the renaming facility is abused, the code can be difficult to read. A renames clause can substitute an abbreviation for a qualifier or long package name locally. This can make code more readable yet anchor the code to the full name. You can use the renames clause to evaluate a complex name once or to provide a new "view" of an object (regardless of whether it is tagged). However, the use of renames clauses can often be avoided or made obviously undesirable by carefully choosing names so that fully qualified names read well.

When a subprogram body calls another subprogram without adding local data or other algorithmic content, it is more readable to have this subprogram body rename the subprogram that actually does the work. Thus, you avoid having to write code to "pass through" a subprogram call (Rationale 1995, §II.12).

The list of renaming declarations serves as a list of abbreviation definitions (see Guideline 3.1.4). As an alternative, you can rename a package at the library level to define project-wide abbreviations for packages and then with the renamed packages. Often the parts recalled from a reuse library do not have names that are as general as they could be or that match the new application's naming scheme. An interface package exporting the renamed subprograms can map to your project's nomenclature. See also Guideline 5.7.1.

The method described in the Ada Reference Manual (1995) for renaming a type is to use a subtype (see Guideline 3.4.1).

The use type clause eliminates the need for renaming infix operators. Because you no longer need to rename each operator explicitly, you avoid errors such as renaming a + to a -. See also Guideline 5.7.1.

notes

You should choose package names to be minimally meaningful, recognizing that package names will be widely used as prefixes (e.g., Pkg.Operation or Object : Pkg.Type_Name;). If you rename every package to some abbreviation, you defeat the purpose of choosing meaningful names, and it becomes hard to keep track of what all the abbreviations represent.

For upward compatibility of Ada 83 programs in an Ada 95 environment, the environment includes
library-level renamings of the Ada 83 library level packages (Ada Reference Manual 1995, §J.1). It is not recommended that you use these renamings in Ada 95 code.