This document Rational Unified Process - Ada Programming Guidelines is a template that can be used to derive a coding standard for your own organization. Its specifies how Ada programs must be written. Its intended audience are all application software designers and developers who use Ada as the implementation language, or as a design language for specifying interfaces or data structures for example.
The rules described in this document cover most aspects of coding. General rules apply to program layout, naming conventions, use of comments. Specific rules apply to selected Ada features and specify forbidden constructs, recommended usage patterns, and general hints to enhance program quality.
There is a certain degree of overlap between the project design guidelines and the present programming guidelines, and this is intentional. Many coding rules, especially in the area of naming conventions, have been introduced to actively support and reinforce an object-oriented approach to software design.
The guidelines were originally written for Ada 83. They include compatibility rules with Ada 95, but no specific guidelines for the use of the new features of the language introduced in the revised language standard, such as tagged types, child units or decimal types.
The document organization follows loosely the structure of the Ada Reference Manual [ISO 8052].
Chapter 2, Introduction, explains the fundamental principles on which the guidelines are based, and introduces a classification of guidelines.
Chapter 3, Code layout, deals with the general visual organization of the text of the programs.
Chapter 4, Comments, gives guidance on how to use comments to document the code in a structured, useful and maintainable fashion.
Chapter 5, Naming conventions, gives some general rules about naming language entities, and examples. This chapter must be tailored to suit the needs of your particular project or organization.
Chapter 6, Declarations, and Chapter 7, Expression and statements, give further advice on each kind of language construct.
Chapter 8, Visibility issues, and Chapter 9, Program structure and compilation issues, give guidance on global structuring and organization of the programs.
Chapter 10, Con currency, deals with the specialized topic of using tasking and time-related features of the language.
Chapter 11, Error-handling and exceptions gives some guidance on how to use or not use exception to handle errors in a systematic and light-weight fashion.
Chapter 12, Low-level programming, deals with issues of representation clauses.
Chapter 13, Summary, recapitulates the most important guidelines.
This document replaces Ada Guidelines: Recommendations for Designers and programmers, Application Note #15, Rational, Santa Clara, CA., 1990.
Ada was explicitly designed to support the development of high-quality, reliable, reusable, and portable software [ISO 87, sect. 1.3]. However, no programming language on its own can ensure that this is achieved. Programming has to be done as part of a well-disciplined process.
Clear, understandable Ada source code is the primary goal of most of the guidelines provided here. This is a major contributing factor to reliability and maintainability. What is meant by clear and understandable code can be captured in the following three simple fundamental principles.
Over its lifetime, source code is read more often than it is written, especially specifications. Ideally, code should read like an English-language description of what is being done, with the added benefit that it executes. Programs are written more for people than for computers. Reading code is a complex mental process that can be supported by uniformity, also referred to in this guide as the minimal-surprise principle. A uniform style across an entire project is a major reason for a team of software developers to agree on programming standards, and it should not be perceived as some kind of punishment or as an obstacle to creativity and productivity.
Another important principle underlying this guide is the single-point-of-maintenance principle. Whenever possible, a design decision should be expressed at only one point in the Ada source, and most of its consequences should be derived programmatically from this point. Violations of this principle greatly jeopardize maintainability and reliability, as well as understandability.
Finally, as a major contribution to legibility, the minimal-noise principle has been applied. That is, an effort has been made to avoid cluttering the source code with visual "noise": bars, boxes, and other text with low information content or information that does not contribute to the understanding of the purpose of the software.
Portability and reusability are also reasons for many of the guidelines. The code will have to be ported to several different compilers for different target computers, and eventually to a more advanced version of Ada, called "Ada 95" [PLO92, TAY92].
The guidelines presented here make a small number of basic assumptions:
The use of advanced Ada features is encouraged wherever beneficial, rather than discouraged on the ground that some programmers are unfamiliar with them. This is the only way in which the project can really benefit from using Ada. Ada should not be used as if it were Pascal or FORTRAN. Paraphrasing the code in comments is discouraged; on the contrary, Ada should be used in place of comments wherever feasible.
Many of the naming conventions are based on English, both vocabulary and syntax. Moreover, Ada keywords are common English words, and mixing them with another language degrades legibility.
Naming conventions and a few other rules assume that "use" clauses are not used.
Many rules offer the most value in large Ada systems, although they can also be used in a small system, if only for the sake of practice and uniformity at the project or corporate level.
By using the Rational Environment, issues such as code layout, identifiers in closing constructs, and so on are taken care of by the Ada editor and formatter. However, the layout recommendations contained in this document can be applied on any development platform.
Many rules will support a systematic mapping of object-oriented (OO) concepts to Ada features and specific naming conventions.
These guidelines are not of equal importance. They roughly follow this scale:
The guideline is a simple piece of advice; there is no real harm done by not following it, and it can be selected or rejected as a matter of taste. Hints are marked in this document with the above symbol.
The guideline is usually based on more technical grounds; portability or reusability may be affected, as well as performance in some implementations. Recommendations must be followed unless there is a good reason not to. Some exceptions are mentioned in this document. Recommendations are marked in this document by the above symbol.
The feature in question is dangerous to use, but it is not completely banned; the decision to use it should be a project-level decision, and that decision should be made highly visible. Restrictions are marked in this document by the symbol presented above.
A violation would definitely lead to bad, unreliable, or non-portable code. Requirements cannot be violated. Requirements are marked in this document the pointing hand above.
Contrary to many other Ada coding standards, very few Ada features are in fact completely banned in these guidelines. The key to good software resides in:
Use common
sense.
When you cannot find a rule or guideline, when the rule obviously does not apply, when everything else fails: use common sense, and check the fundamental principles. This rule overrides all of the others. Common sense is required.
The layout of a program unit is completely under the control of the Rational Environment Formatter, and the programmer should not have to worry too much about the layout of a program, except in comments and blank space. The formatting conventions adopted by this tool are those expressed in Appendix E of the Reference Manual for the Ada Programming Language [ISO87]. In particular, they suggest that the keywords starting and ending a structured construct be vertically aligned. Also the identifier of a construct is systematically repeated at the end of the construct.
The precise behavior of the formatter is controlled by a series of library switches which receive a uniform set of values throughout the project, based on a common model world. The relevant switches are listed below with their current value for the model world we recommend.
Specifies the case of identifiers in Ada units: the very first letter, and each first letter after an underscore are in uppercase. The capitalized form is recognized as the most legible form by human readers, with most modern screen and laser printer fonts.
Specifies the case of Ada keywords. This distinguishes them slightly from identifiers.
Specifies the case of the letter "E" in floating-point literals and based digits ("A" to "F") in based literals.
An Ada unit is formatted according to the general conventions expressed in Appendix E of the Ada Reference Manual [ISO87]. This means that the keywords starting and ending a structured construct are aligned. For example, "loop" and "end loop", "record" and "end record". Elements that are inside structured constructs are indented to the right.
Specifies the number of columns that the formatter indents structured (major) constructs such as "if" statements, "case" statements, and "loop" statements.
Specifies the number of columns that the formatter indents minor constructs: record declarations, variant record declarations, type declarations, exception handlers, alternatives, case statements, and named and labeled statements.
Specifies the number of columns used by the formatter for printing lines in Ada units before wrapping them. This allows the display of formatted units with traditional VT100 like terminals.
Specifies the number of columns the formatter indents the second and subsequent lines of a statement when the statement has to be broken because it is longer than Line_Length. The formatter indents Statement_Indentation number of columns only if there is no lexical construct with which the indented code can be aligned.
Specifies the number of columns reserved on each line to display a statement. If the current level of indentation allows for fewer than Statement_Length columns on a line, then the formatter starts over with the Wrap_Indentation column as its new level of indentation. This practice prevents deeply nested statements from being printed beyond the right margin.
Specifies the column at which the formatter begins the next level of indentation when the current level of indentation does not allow for Statement_Length. This practice prevents deeply nested statements from being printed beyond the right margin.
Controls the formatting of lists of the form (xxx:aaa; yyy:bbb), which appear in subprogram formal parts and as discriminants in type declarations. It also controls formatting of lists of the form (xxx=>aaa, yyy=>bbb), which appear in subprogram calls and aggregates. Since this option is non-zero (True), when a list does not fit on a line, every element of the list begins on a new line.
Specifies the number of blank spaces that the formatter can insert to align lexical constructs in consecutive statements, such as colons, assignments, and arrows in named notation. If more than this number of spaces would be needed to align a construct, the construct is left unaligned.
Note that in
order to force a certain layout, the programmer can insert an end-of-line, or
line break that will not be removed by the formatter by entering <space>
<space> <carriage-return>.
Using this
technique, and in order to improve legibility and maintainability, lists of Ada
elements should be broken to contain only one element per line, when the list
exceeds 3 items, and when they do not fit on one line. In particular this
applies to the following Ada constructs (as defined in Appendix E of the Ada
Reference Manual [ISO87]):
argument association
pragma Suppress (Range_Check,
On => This_Type,
On => That_Type, On => That_Other_Type);
identifier list, component list
Next_Position,
Previous_Position,
Current_Position : Position;
type Some_Record is
record
A_Component,
B_Component,
C_Component : Component_Type;
end record;
enumeration type definition
type Navaid is
(Vor,
Vor_Dme,
Dme,
Tacan,
VorTac,
NDB);
discriminant constraint
subtype Constrained is Element
(Name_Length => Name'Length,
Valid => True,
Operation => Skip);
sequence of statements (done by formatter)
formal part, generic formal part, actual parameter part, generic actual parameter part
procedure Just_Do_It (This : in Some_Type;
For_That : in Some Other_Type;
Status : out Status_Type);
Just_Do_It (This => This_Value;
For_That => That_Value;
Status => The_Status);
Contrary to a widely held belief, good programs are not characterized by the number of comments, but by their quality.
Comments should be used to complement Ada code, never to paraphrase it. Ada by itself is a very legible programming language-even more so when supported by good naming conventions. Comments should supplement Ada code by explaining what is not obvious; they should not duplicate the Ada syntax or semantics. Comments should help the reader to grasp the background concepts, the dependencies, and especially complex data encoding or algorithms. Comments should highlight deviations from coding or design standards, use of restricted features, and special "tricks." Comment frames, or forms, that appear systematically for each major Ada construct (such as subprograms and packages) have the benefit of uniformity and of reminding the programmer to document the code, but they often lead to a paraphrasing style. For each comment, the programmer should be able to answer well the question: "What value is added by this comment?"
A misleading or wrong comment is worse than no comment at all. Comments (unless they participate in some formal Ada Design Language (ADL) or Program Design Language (PDL), as with the Rational Design Facility) are not checked by the compiler. Therefore, in accordance with the single-point-of-maintenance principle, design decisions should be expressed in Ada rather than in comments, even at the expense of a few more declarations.
As a (not so good) example, consider the following declaration:
------------------------------------------------------------
-- procedure Create
------------------------------------------------------------
--
procedure Create
(The_Subscriber: in out Subscriber.Handle;
With_Name : in out Subscriber.Name);
--
-- Purpose: This procedure creates a subscriber with a given
-- name.
--
-- Parameters:
- The_Subscriber :mode in out, type Subscriber.Handle
- It is the handle to the created subscriber
- With_Name :mode in, type Subscriber.Name
- The name of the subscriber to be created.
- The syntax of the name is
-- <letter> { <letter> | <digit> }
-- Exceptions:
-- Subscriber.Collection_Overflow when there is no more
-- space to create a new subscriber
-- Subscriber.Invalid_Name when the name is blank or
-- malformed
--
-------------------------------------------- end Create ----
Several points can be made about this example.
In this case, the following more concise and useful version is preferred:
procedure Create (The_Subscriber : in out Subscriber.Handle;
With_Name : in Subscriber.Name);--
--Raises Subscriber.Collection_Overflow.
--Raises Subscriber.Invalid_Name when the name is
--blank or malformed (see syntax description
--attached to declaration of type Subscriber.Name).
Comments
should be placed near the code they are associated with, with the same
indentation, and attached to that code-that is, with blank comment line(s)
visually tying the block of comments to the Ada construct:
procedure First_One; -- -- This comment relates to First_One. -- But this comment is for Second_One. -- procedure Second_One (Times : Natural);
Use blank
lines to separate related blocks of source code (comments and code) rather than
heavy comment lines.
Use empty
comments, rather than empty lines, within a single comment block to separate
paragraphs:
-- Some explanation here that needs to be continued in a -- subsequent paragraph. -- -- The empty comment line above makes it clear that we -- are dealing with a single comment block.
Although
comments can be placed above or below the Ada construct(s) to which they are
related, place comments such as a section title or a major piece of information
that applies to several Ada constructs above the construct(s). Place
comments that are remarks or additional information below the Ada
construct to which they apply.
Group
comments at the beginning of the Ada construct, using the whole width of the
page. Avoid comments on the same line as an Ada construct. These comments often
become misaligned. Such comments are tolerated, however, in descriptions of each
element in long declarations, such as enumeration type literals.
Use a small
hierarchy of standard blocks of comments for section titles, but only in very
large Ada units (>200 declarations or statements):
--=========================================================== -- -- MAJOR TITLE HERE -- --=========================================================== ------------------------------------------------------------- -- Minor Title Here ------------------------------------------------------------- -- -------------------- -- Subsection Header -- --------------------
Put more blank lines above such title comments than below-for example, two lines before and one line after. This visually associates the title with the following text.
Avoid the
use of headers containing information such as author, phone numbers, dates of
creation and modification, and location of unit (or filename), because this
information rapidly becomes obsolete. Place ownership copyright notices at the
end of the unit, especially when using the Rational Environment. When accessing
the source of a package specification-by pressing [Definition] on the Rational
Environment, for instance-the user does not want to have to scroll through two
or three pages of text that is not useful for the understanding of the program,
and/or text that does not carry any program information at all, such as a
copyright notice. Avoid the use of vertical bars or closed frames or boxes,
which just add visual noise and are difficult to keep consistent. Use Rational
CMVC notes (or some other form of software development files) to keep unit
history.
Do not
replicate information normally found elsewhere; provide a pointer to the
information.
Use
Ada wherever possible, rather than a comment. To achieve this, you can use better
names, extra temporary variables, qualification, renaming, subtypes, static
expressions, and attributes, all of which do not affect the generated code (at
least with a good compiler). You can also use small, inline predicate functions
and split the code into several parameter-less procedures, whose names provide
titles for several discrete sections of code.
Examples:
Replace:
exit when Su.Locate (Ch, Str) /= 0; -- Exit search loop when found it.
Search_Loop : loop
Found_It := Su.Locate (Ch, Str) /= 0;
exit Search_Loop when Found_It
end Search_Loop;
Replace:
if Value < 'A' or else Value > 'Z' then -- If not in uppercase letters.
subtype Uppercase_Letters is Character range 'A' .. 'Z'; if Value not in Uppercase_Letters then ...
Replace:
X := Green; -- This is the Green from
-- Status, not from Color.
raise Fatal_Error; -- From package Outer_Scope.
delay 384.0; -- Equal to 6 minutes and 24
-- seconds.
The_Status := Green;
X := Status'(Green); raise Outer_Scope.Fatal_Error; delay 6.0 * Minute + 24.0 * Second;
Replace:
if Is_Valid (The_Table (Index).Descriptor(Rank).all) then -- This is the current value for the iteration; if it is -- valid we append to the list it contains. Append (Item, To_List => The_Table (Index).Descriptor(Rank).Ptr);|
declare
Current_Rank : Lists.List renames The_Table
(Index).Descriptor (Rank);
begin
if Is_Valid (Current_Rank.all) then
Append (Item, To_List => Current_Rank.Ptr);
end if;
end;
Take care
with style, syntax, and spelling in comments. Do not use a telegraphic, cryptic
style. Use a spelling checker. (On the Rational Environment invoke
Speller.Check_Image).
Do not use
accented letters or other non-English characters. Non-English characters may be
supported on some development systems and on some Ada compilers in comments
only, according to Ada Issue AI-339. But this is not portable, and it is likely
to fail on other systems.
For
subprograms, document at least:
For types
and objects, document any invariant, or additional constraints that cannot be
expressed in Ada.
Avoid
repetitions in comments. For example, the purpose section should be a brief
answer to the question "what does this do?" and not "how is it
done?" The overview should be a brief presentation of the design. The
description should not describe the algorithms used, but should instead explain
how the package is to be used.
The Data_Structure and algorithm section should contain enough information to help understand the main implementation strategy (so that the package can be used properly), but does not have to provide all implementation details, or information that is not relevant to the proper use of this package.
Choosing good names to designate Ada entities (program units, types, subtypes, objects, literals, exceptions) is one of the most delicate issues to address in all software applications. In medium-to-large applications, another problem arises: conflicts in names, or rather the difficulty in finding enough synonyms to designate distinct but similar notions about the same real-world concept (or to name a type, subtype, object, parameter). Here the rule not to use "use" clauses (or only in highly restricted conditions) can be exploited. In many situations, this will permit the shortening of a name and the reuse of the same descriptive words without risk of confusion.
Choose
clear, legible, meaningful names.
Unlike many other programming languages, Ada does not limit the length of identifiers to 6, 8, or 15 characters. Speed of typing is not an acceptable justification for short names. One-letter identifiers are usually an indication of poor choice or laziness. There might be a few exceptions, such as using E for the base of the natural logarithms, Pi, or a handful of other well-recognized cases.
Separate
various words of a name by an underscore:
Is_Name_Valid rather than IsNameValid
Use full
names rather than abbreviations.
Use only
project-approved abbreviations
If abbreviations are used, either they must be very common to the application domain (for example, FFT for Fast Fourier Transform) or they should be taken out of a project-level list of recognized abbreviations. Otherwise, it is very likely that similar but not quite identical abbreviations will occur here and there, introducing confusion and errors later (for example, Track_Identification being abbreviated Tr_Id, Trck_Id, Tr_Iden, Trid, Tid, Tr_Ident, and so on).
Use
sparingly suffixes indicating category of Ada construct. They do not improve
legibility.
Suffixes by category of Ada entities, such as _Package for packages, _Error for exceptions, _Type for type, and _Param for subprogram parameters are usually not very effective for the process of reading and understanding the code. This is even worse with suffixes such as _Array, _Record, and _Function. Both the Ada compiler and the human reader can distinguish an exception from a subprogram by the context: it is obvious that only an exception name can appear in a raise statement or in an exception handler. Such suffixes are useful in the following limited situations:
Generic formal type suffixed by _Constrained
Access type suffixed by _Pointer or other form of indirect reference: by _Handle, or _Reference
Subprogram hiding a potentially blocking entry call by _Or_Wait
Express
names so that they look nice from the usage point of view.
Try to think about the context in which an exported entity will be used, and choose the name from that point of view. An entity is declared once and used many times. This is especially true for subprogram names and their parameters: the resulting calls, using named associations, should be as close as possible to natural language. Remember that the absence of use clauses will make compulsory the qualified name of most declared entities. Good compromises have to be found for generic formal parameters, which may be used more in the generic unit than on its client side, but definitely give preference to a nice look on the client side for subprogram formal parameters.
Use English
words and spell them correctly.
Language mixture (for example, French and English) makes the code difficult to read and sometimes introduces ambiguities in the meaning of identifiers. Since Ada keywords are already in English, English words are required. American spelling is preferred, in order to be able to use the built-in spelling checker on the Rational Environment.
Do not
redefine any entity from package Standard. This is absolutely forbidden.
To do so leads to confusion and dramatic mistakes. The rule could be extended to other predefined library units: Calendar, System. And this includes the identifier Standard itself.
Avoid the
redefinition of identifiers from other predefined packages, such as System, or
Calendar.
Do not use
as identifiers: Wide_Character and Wide_String which will be
introduced in package Standard in Ada 95. Do not introduce a compilation unit
named Ada.
Do
not use as identifiers the words: abstract, aliased, protected,
requeue, tagged and until, which will become keywords in
Ada 95.
Some naming suggestions for various Ada entities follow. A generally "object-flavored" style of design is assumed. See Annex A for further explanations.
When a
package introduces some object class, give it the name of the object class,
usually a common noun in singular form, with the suffix _Generic if necessary
(that is, if a parameterized class is defined). Use the plural form only if the
objects always come in groups. For example:
package Text is package Line is package Mailbox is package Message is package Attributes is package Subscriber is package List_Generic is
When a
package specifies an interface or some grouping of functionality, and does not
relate to an object, express this in the name:
package Low_Layer_Interface is package Math_Definitions is
When a
"logical" package needs to be expressed as several packages, using a
flat decomposition, use suffixes drawn from a list agreed upon at the project
level. A logical package Mailbox, for example, could be implemented with:
package Mailbox_Definitions is package Mailbox_Exceptions is package Mailbox_Io is package Mailbox_Utilities is package Mailbox_Implementation is package Mailbox_Main is
Other acceptable suffixes are:
_Test_Support _Test_Main _Log _Hidden_Definitions _Maintenance _Debug
In a package
defining an object class, use:
type Object is ...
when copy semantics is implied-that is, when the type is instantiable and some form of assignment is feasible. Note that the name of the class should not be repeated in the identifier, since it will always be used in its fully qualified form:
Mailbox.Object Line.Object
When shared
semantics is implied-that is, the type is implemented with access values (or
some other form of indirection), and assignment, if available, does not copy the
object-indicate this fact by using:
type Handle is for an indirect referencetype Reference is as a possible alternate
The elements are used as suffixes when their use alone, prefixed by the package name, is unclear or ambiguous.
When multiple objects are implied, use one of the following:
type Settype Listtype Collectiontype IteratorFor some
string designation of the object, use:
type Name
The
qualified name of the type should also be used throughout the defining package,
for better legibility. On the Rational Environment, this also leads to better
behavior when using the [Complete] function on a subprogram call.
For example, note the full name Subscriber.Object below:
package Subscriber is
type Object is private;
type Handle is access Subscriber.Object;
subtype Name is String;
package List is new List_Generic (Subscriber.Handle);
Master_List : Subscriber.List.Handle;
procedure Create (The_Handle : out Subscriber.Handle;
With_Name : in Subscriber.Name);
procedure Append (The_Subscriber : in Subscriber.Handle;
To_List : in out Subscriber.List.Handle);
function Name_Of (The_Subscriber : Subscriber.Handle) return
Subscriber.Name;
...
private
type Object is
record
The_Name : Subscriber.Name (1..20);
...
end Subscriber;
In other
circumstances, use nouns or qualifier+noun for the name of a type. You might use
the plural form for the type, leaving the singular for objects (variables):
type Point is record ... type Hidden_Attributes is ( ... type Boxes is array ...
For enumeration types, use Mode, Kind, Code, and so on, alone or as a suffix.
For array types, the suffix _Table can be used when the simple name is already used for the component type. Use names or suffixes like _Set and _List only when the array is maintained with the implied semantics. Reserve _Vector and _Matrix for the corresponding mathematical concepts.
Since
singular task objects will be avoided (for reasons explained later), a task type
should be introduced even when there is only one object of that type. This is a
case where a simple-minded suffix strategy such as _Type is satisfactory:
task type Listener_Type is ... for Listener_Type'Storage_Size use ... Listener : Listener_Type;
Similarly, when ambiguity exists from the use of a noun (or noun phrase) for the name of the type and for the name of the object or parameter, then append the suffix _Kind to the name of the type and keep the simple noun for the object.
type Status_Kind is (None, Normal, Urgent, Red); Status : Status_Kind := None;
Or, for
things that always come in multiples, use the plural form for the type.
Since access
types have inherent dangers, the user should be made aware of them. They are
called Pointer in general. Use the suffix _pointer if the name alone is
ambiguous. As an alternate _Access is possible. ;
Sometimes
using a nested subpackage to introduce a secondary abstraction simplifies
naming:
package Subscriber is ...
package Status is
type Kind is (Ok, Deleted, Incomplete, Suspended,
Privileged);
function Set (The_Status : Subscriber.Status.Kind;
To_Subscriber : Subscriber.Handle);
end Status;
...
Since
exceptions must be used only to handle error situations, use a noun or a noun
phrase that clearly conveys a negative idea:
Overflow, Threshold_Exceeded, Bad_Initial_Value
When defined in a class package, it is useless for the identifier to contain the name of the class-for example, Bad_Initial_Subscriber_Value-since the exception will always be used as Subscriber.Bad_Initial_Value.
Use one of
the words Bad, Incomplete, Invalid, Wrong, Missing, or Illegal as part of the
name rather than systematically using Error, which does not convey specific
information:
Illegal_Data, Incomplete_Data
Use verbs
for procedures (and task entries). Use nouns with the attributes or
characteristics of the object class for functions. Use adjectives (or past
participles) for functions returning a Boolean (predicates). s
Subscriber.Create Subscriber.Destroy Subscriber.List.Append Subscriber.First_Name -- Returns a string. Subscriber.Creation_Date -- Returns a date. Subscriber.List.Next Subscriber.Deleted -- Returns a Boolean. Subscriber.Unavailable -- Returns a Boolean. Subscriber.Remote
For
predicates, it may be useful in some cases to add the prefix Is_ or Has_ before
a noun; be accurate and consistent with respect to tense:
function Has_First_Name ... function Is_Administrator ... function Is_First... function Was_Deleted ...
This is useful when the simple name is already used as a type name or an enumeration literal.
Use predicates in the positive form, i.e., they should not contain "Not_".
For common operations, consistently use verbs drawn from a project list of choices (list to be expanded as we gain knowledge of the system):
Create Delete Destroy Initialize Append Revert Commit Show, Display
Use positive
names for predicate functions and Boolean parameters. Using negative names can
create double negations (e.g., Not Is_Not_Found), and can make the code more
difficult to read.
function Is_Not_Valid (...) return Boolean
procedure Find_Client (With_The_Name : in Name;
Not_Found : out Boolean)
should be defined as:
function Is_Valid (...) return Boolean;
procedure Find_Client (With_The_Name: in Name;
Found: out Boolean)
which lets the client negate their expression as required (there is no runtime penalty for doing so):
if not Is_Valid (...) then ....
In some cases, a negative predicate can also be made positive without changing its semantics by using an antonym, such as "Is_Invalid" instead of "Is_Not_Valid." However, positive names are more readable: "Is_Valid" is easier to understand than "not Is_Invalid."
Use the same
word when the same general meaning is implied, rather than trying to find
synonyms or variations. Overloading therefore is encouraged to enhance
uniformity, in keeping with the principle of minimal surprise.
If
subprograms are used as "skins" or "wrappers" for entry
calls, it may be useful that the name reflects this fact by suffixing the verb
with _Or_Wait or by having a phrase such as Wait_For_ followed by a noun:
Subscriber.Get_Reply_Or_Wait Subscriber.Wait_For_Reply
Some operations should always be consistently defined using the same names:
For type
conversions to and from strings, the symmetrical functions:
function Image and function Value
For type
conversions to and from some low-level representation (such as Byte_String for
data interchange):
procedure Read and Write
For
allocated data:
function Allocate (rather than Create)
function Destroy (or Release, to express that the object will disappear)
When this is done systematically, using consistent naming, type composition is made much easier.
For active
iterators, the following primitives must always be defined:
Initialize Next Is_Done Value_Of Reset. If several iterator types are introduced in the same scope, these primitives should be overloaded rather than introducing a distinct set of identifiers for each iterator. Cf. [BOO87].
When using
Ada predefined attributes as function names, make sure that they are used with
the same general semantics: 'First, 'Last, 'Length, 'Image, 'Value, and so on.
Note that several attributes (for example, 'Range and 'Delta) cannot be used as
function names because they are reserved words.
To indicate
uniqueness, or to show that this entity is the main focus of the action, prefix
the object or parameter name with The_ or This_. To indicate a side, temporary,
auxiliary object, prefix it with A_ or Current_:
procedure Change_Name (The_Subscriber : in Subscriber.Handle;
The_Name : in Subscriber.Name );
declare
A_Subscriber : Subscriber.Handle := Subscriber.First;
begin
...
A_Subscriber := Subscriber.Next (The_Subscriber);
end;
For Boolean
objects, use a predicate clause, with the positive form:
Found_It Is_Available
Is_Not_Available must be avoided.
For task
objects, use a noun or noun phrase that implies an active entity:
Listener Resource_Manager Terminal_Driver
For
parameters, prefixing the class name or some characteristic noun with a
preposition also adds legibility, especially on the caller's side when named
association is used. Other useful prefixes for auxiliary parameters have the
form Using_ or, in the case of an in out parameter that is affected as
some secondary effect, Modifying_:
procedure Update (The_List : in out Subscriber.List.Handle;
With_Id : in Subscriber.Identification;
On_Structure : in out Structure;
For_Value : in Value);
procedure Change (The_Object : in out Object;
Using_Object : in Object);
The order
in which parameters are defined is also very important from the caller's point
of view:
This permits taking advantage of defaults without having to use named association for the main parameter(s).
The mode
"in" must be explicitly indicated, even in functions.
Pick the
best name you would use for a non-generic version: class name for a package or
transitive verb (or verb phrase) for a procedure (see above) and suffix it with
_Generic.
For generic
formal types, when the generic package defines some abstract data structure, use
Item or Element for the generic formal and Structure,
or some other more appropriate noun, for the exported abstraction.
For passive
iterators, use a verb such as Apply, Scan, Traverse,
Process, or Iterate in the identifier:
generic with procedure Act (Upon : in out Element); procedure Iterate_Generic (Upon : in out Structure);
Names of
generic formal parameters cannot be homographs.
generic
type Foo is private;
type Bar is private;
with function Image (X : Foo) return String;
with function Image (X : Bar) return String;
package Some_Generic is ...
shall be replaced by:
generic
type Foo is private;
type Bar is private;
with function Foo_Image (X : Foo) return String;
with function Bar_Image (X : Bar) return String;
package Some_Generic is ...
If needed, the generic formal parameters can be renamed in the generic unit:
function Image (Item : Foo) return String Renames Foo_Image; function Image (Item : Bar) return String Renames Bar_Image;
When a large system is partitioned into Rational subsystems (or another form of interconnected program libraries), it is useful to define a naming strategy that allows:
In a system that comprises several hundred objects and sub-objects, some name conflicts are likely to occur at the library-unit level, and programmers will be short of synonyms for some very useful names like Utilities, Support, Definitions, and so on.
Using browsing facilities on the Rational host, finding where an entity is defined is an easy task, but when code is ported to a target and uses target tools (debuggers, testing tools, and so on), the location of a procedure Utilities.Get among 2,000 units in 100 subsystems may be quite a challenge for a newcomer to the project.
Prefix
library-level unit names with the four-letter abbreviation of the subsystem in
which it is contained.
The list of subsystems can be found in the Software Architecture Document (SAD). Exclude from this rule libraries of highly reusable components that are likely to be reused across numerous projects, COTS products, and standard units.
Example:
Comm Communication
Dbms Database management
Disp Displays
Math Mathematical packages
Drive Drivers
For example, all library units exported from subsystem Disp will be prefixed with Disp_, allowing the team or company in charge of Disp to have otherwise complete freedom of naming. If both DBMS and Disp need to introduce an object class named Subscriber, this will result in packages such as :
Disp_Subscriber Disp_Subscriber_Utilities Disp_Subscriber_Defs Dbms_Subscriber Dbms_Subscriber_Interface Dbms_Subscriber_Defs
Ada's strong
typing facility will be used to prevent mixing of different types. Conceptually
different types must be realized as different user-defined types. Subtypes
should be used to improve program readability and to enhance the effectiveness
of the run-time checks generated by the compiler.
Whenever
possible, introduce into the enumeration some extra literal value representing
uninitialized, invalid, or no value at all:
type Mode is (Undefined, Circular, Sector, Impulse); type Error is (None, Overflow, Invalid_Input_Value,Ill-formed_Name);
This will support the rules for systematically initializing objects. Put this literal at the beginning rather than at the end of the list, to ease maintenance and to allow contiguous subranges of valid values such as:
subtype Actual_Error is Error range Overflow .. Error'Last;
Avoid the
use of predefined numeric types.
When a high degree of portability and reusability is the objective, or when control is needed over the memory space occupied by numeric objects, then predefined numeric types (from package Standard) must not be used. The reason for this requirement is that the characteristics of the predefined types Integer and Float are (deliberately) unspecified in the Reference Manual for the Ada Programming Language [ISO87].
A first
systematic strategy is to introduce project-specific numeric types-in a package
System_Types, for instance-with names that carry an indication of the accuracy
or memory size:
package System_Types is
type Byte is range -128 .. 127;
type Integer16 is range -32568 .. 32567;
type Integer32 is range ...
type Float6 is digits 6;
type Float13 is digits 13;
...
end System_Types;
Do not
redefine standard types (types from package Standard).
Do not
specify which base type they should be derived from; let the compiler choose.
This following example is bad:
type Byte is new Integer range -128 .. 127;
Float6 is a
better name than Float32, even if on most machines 32-bit floats will achieve 6
digits of accuracy.
In the
various parts of the project, derive types with more meaningful names than those
in Baty_System_Types. Some of the most accurate types could be made private to
support an eventual port to a target with limited precision support.
This strategy is to be used when:
If this is not the case, then another simpler strategy is to always define new types, specifying the requested range and accuracy, but never specifying the base type they should be derived from. For example, declare:
type Counter is range 0 .. 100; type Length is digits 5;
This is preferrable to the following:
type Counter is new Integer range 1..100; -- could be 64 bits type Length is new Float digits 5; -- could be digits 13
This second strategy forces the programmer to think of the precise bounds and accuracy each type requires, rather than arbitrarily selecting a certain number of bits. Be aware, however, that if the range is not identical to that of a base type, systematic range checks will be applied by the compiler-for example, for type Counter above, if the base type is a 32-bit integer.
If the range
checks are becoming a problem, one way to avoid them is to declare:
type Counter_Min_Range is range 0 .. 10_000; type Counter is range Counter_Min_Range'Base'First .. Counter_Min_Range'Base'Last;
Avoid
standard types leaking into the code through constructs such as loops, index
ranges, and so on.
Subtypes of the predefined numeric types are used only in the following circumstances:
Example:
for I in 1 .. 100 loop ... -- I is of type Standard.Integer type A is array (0 .. 15) of Boolean; -- index is Standard.Integer.
Use instead the form: Some_Integer range L .. H
for I in Counter range 1 .. 100 loop ... type A is array (Byte range 0 .. 15) of Boolean;
Do not try
to implement unsigned types.
Integer types with unsigned arithmetic do not exist in Ada. Under the language definition, all integer types are derived indirectly or not from the predefined types, and these in turn must be symmetrical about zero.
For
portability, rely only on real types having values in the ranges:
[-F'Large .. -F'Small] [0.0] [F'Small .. F'Large]
Be aware that F'Last and F'First may not be model numbers and may even not be in any model interval. The relative location of F'Last and F'Large depends on the type definition and the underlying hardware. One particularly nasty example is the case where 'Last of a fixed-point type does not belong to the type, as in:
type FF is delta 1.0 range -8.0 .. 8.0;
where, according to a strict reading of the Ada Reference Manual 3.5.9(6), FF'Last = 8.0 cannot belong to the type.
To represent large or small real numbers, use attributes 'Large or 'Small (and their negative counterparts), not 'First and 'Last, as would be done for integer types.
For
floating-point types, use only <= and >=, never =, <, >, /=.
The semantics of absolute comparison are ill-defined (equality of representation and not equality within the required degree of accuracy). For example, X < Y may not yield the same result as: not (X >= Y). Tests for equality, A = B, should be expressed as:
abs (A - B) <= abs(A)*F'Epsilon
To improve readability and maintainability, consider providing an Equal operator that encapsulates the above expression.
Note also that the simpler expression:
abs (A - B) <= F'Small
is valid only for small values of A and B, and therefore is not generally recommended.
Avoid any
reference to the predefined exception Numeric_Error. A binding interpretation of
the Ada Board has made all cases that used to raise Numeric_Error now raise
Constraint_Error. The exception Numeric_Error is obsolete in Ada 95.
If
Numeric_Error is still raised by the implementation (this is the case of the
Rational native compiler), then always check for Constraint_Error together with
Numeric_Error in the same alternative in an exception handler:
when Numeric_Error | Constraint_Error => ...
Be wary of
underflow.
Underflow is not detected in Ada. The result is 0.0 and no exception is raised. Note that a check for underflow can be explicitly achieved by testing the result of a multiplication or division against 0.0, when none of the operands is 0.0. Note also that you can implement your own operators to automatically perform such checking, although at some cost in efficiency.
The use of
fixed-point types is restricted.
Use floating-point types whenever possible. The use of fixed-point types may cause portability problems.
For
fixed-point types, 'Small should be equal to 'Delta.
The code should specify this. The fact that the default choice for 'Small is a power of 2 leads to all kinds of problems. One way to make the choice clear is to write:
Fx_Delta : constant := 0.01; type FX is delta Fx_Delta range L .. H; for FX'Small use Fx_Delta;
If length clauses for fixed-point types are not supported, the only way to obey this rule is to specify explicitly a 'Delta that is a power of 2. Subtypes can have a 'Small different from 'Delta (the rule applies only to the type definition, or "first named subtype" in the terminology of the Ada Reference Manual).
Wherever
possible, provide simple, static initial values for the components of a record
type (often values such as 'First or 'Last can be used).
But do not apply this to discriminants. The rules of the language are such that discriminants always have values. Mutable records (that is, records with default values for discriminants) should be introduced only when mutability is a wanted characteristic. Otherwise, mutable records introduce extra overhead in memory space (often the largest variant is allocated) and time (variant checks are more complex to achieve).
Avoid
function calls in default initial values of any component, since this may lead
to an "access before elaboration" error (see "Program Structure
and Compilation Issues").
For mutable
records (records whose discriminants have default values), if a discriminant is
used in the dimensioning of some other component, specify it to be of a
reasonable small range.
Example:
type Record_Type (D : Integer := 0) is
record
S : String (1 .. D);
end record;
A_Record : Record_Type;
is likely to raise a Storage_Error on most implementations. Specify a more reasonable range for the subtype of the discriminant D.
Do not
assume anything about the physical layout of records.
Especially, and unlike other programming languages, components need not be laid out in the order given in the definition.
Restrict the
use of access types.
This is especially true for applications that are meant to run permanently on small machines without virtual memory. Access types are dangerous, since small programming mistakes can lead to storage exhaustion and, even with good programming, can fragment memory. Access types are also slower. The use of access types must be part of a project wide strategy, and collections, their size, and points of allocation and deallocation should be tracked. The name chosen for an access type should indicate its nature, for example, Pointer or a name suffixed by _Pointer.
Allocate
collections during program elaboration, and systematically specify the size of
each collection.
The value given (in storage units) can be static or computed dynamically (read from a file, for instance). The rationale for this rule is that the program should fail immediately at startup, rather than die mysteriously N days later. Generic packages may provide for this with an additional generic formal specifying the size.
Note that there is often some overhead for each allocated object: it may be that the runtimes on the target system allocate some additional information with each memory chunk for internal housekeeping. So, to store N objects of size M storage units, it may be necessary to allocate more than N * M storage units for the collection-for example, N * (M + K). Obtain the value of this overhead K from Appendix F of [ISO87] or by conducting experiments.
Encapsulate
the use of allocators (Ada primitive new) and release. If feasible,
manage an internal free list, rather than relying on Unchecked_Deallocation.
If an access type is used to implement some recursive data structure, then it is very likely to access a record type that has (as one component) that same access type. This allows recycling of free cells by chaining them in a free list with no additional space overhead (other than the pointer to the head of the list).
Handle explicitly Storage_Error exceptions raised by new, and re-export a more meaningful exception, indicating exhaustion of the collection's maximum storage size.
Having a single point of allocation and deallocation also allows easier tracing and debugging in case of a problem.
Use
deallocation only on allocated cells of the same size (hence same
discriminants).
This is important in order to avoid memory fragmentation. Unchecked_Deallocation is very unlikely to provide a memory-compaction service. You may want to check whether the runtime system provides coalescing of adjacent released blocks.
Systematically
provide a Destroy (or Free, or Release) primitive with access types.
This is especially important for abstract data types implemented with access types, and it should be done systematically to achieve the ability to compose multiple such types.
Release
objects systematically.
Try to map the calls to allocation and deallocation to make sure that all allocated data is deallocated. Try to deallocate data in the same scope in which it was allocated. Remember to deallocate also when exceptions occur. Note that this is one case for using a when others alternative, ending with a raise statement.
The preferred strategy is to apply the pattern: Get-Use-Release. The program Gets the object (which creates some dynamic data structure), then Uses the object, then must Release the object. Make sure that the three operations are clearly identified in the code, and that the release is done on all possible exits of the frame, including by exception.
Be careful
to deallocate the temporary composite data structures which might be contained
in records.
Example:
type Object is
record
Field1: Some_Numeric;
Field2: Some_String;
Field3: Some_Unbounded_List;
end record;
where 'Some_Unbounded_List' is a composite linked structure, that is, it is composed of a number of objects linked together. Consider now a typical attribute function, written as:
function Some_Attribute_Of(The_Object: Object_Handle) return
Boolean is Temp_Object: The_Object;
begin
Temp_Object := Read(The_Object);
return Temp_Object.Field1 < Some_Value;
end Some_Attribute_Of;
The composite structure implicitly created in the heap when the object is read into Temp_Object is never deallocated, but is now unreachable. This is a memory leak. The proper solution is to implement a Get-Use-Release paradigm for such expensive structures. In other words, your client should Get the object first, then Use it as needed, then Release it:
procedure Get (The_Object : out Object;
With_Handle : in Object_Handle);
function Some_Attribute_Of(The_Object : Object)
return Some_Value;
function Other_Attribute_Of(The_Object : Object)
return Some_Value;
...
procedure Release(The_Object: in out Object);
The client code might look like this:
declare
My_Object: Object;
begin
Get (My_Object, With_Handle => My_Handle);
...
Do_Something
(The_Value => Some_Attribute_Of(My_Object));
...
Release(My_Object);
end;
Declare
types as private whenever it is necessary to hide implementation details.
Implementation details need to be hidden with a private type when:
In the Rational Environment, private types, in conjunction with closed private parts and subsystems, greatly reduce the impact of an eventual interface design change.
In
contradiction to so-called "pure" object-oriented programming, do not
use private types when the corresponding complete type is the best
possible abstraction. Be pragmatic; ask if making the type private adds
anything.
For example, a mathematical vector is better represented as an array, or a point in a plane as a record, than as a private type:
type Vector is array (Positive range <>) of Float;
Type Point is
record
X, Y : Float := Float'Large;
end record;
Array indexing, record component selection, and aggregate notation will be far more legible (and eventually more efficient) than a series of subprogram calls, as would be required were the type unnecessarily private.
Declare
private types as limited when default assignment or comparison of the
actual objects and values is meaningless, non-intuitive, or impossible.
This is the case when:
A limited
private type should be self-initializing.
An object declaration of such a type must receive a reasonable initial value, since generally it will not be feasible to assign a later one, without risk of raising some exception during a subprogram call.
Whenever
feasible or meaningful, provide for limited types a Copy (or Assign) procedure
and a Destroy procedure.
When
designing a generic's formal types, specify limited private types as long
as equality or assignment is not required internally, for greater usability of
the corresponding generic unit.
In line with the previous rule, you might then import a Copy and a Destroy generic formal procedure and an Are_Equal predicate, if meaningful.
For generic
formal private types, indicate in the specification whether the corresponding
actual must be constrained or not.
This can be achieved by a naming convention and/or comment:
generic
--Must be constrained.
type Constrained_Element is limited private;
package ...
Alternately you can use the Rational-defined pragma Must_Be_Constrained:
generic
type Element is limited private;
pragma Must_Be_Constrained (Element);
package ...
Remember
that deriving a type also derives all the subprograms that are declared in the
same declarative part as the parent type: the derivable subprograms. It is
therefore useless to redefine them all as skins in the declarative part of the
derived type. But generic subprograms are not derivable and it may be necessary
to redefine them as skins.
Example:
package Base is
type Foo is
record
...
end record;
procedure Put(Item: Foo);
function Value(Of_The_Image: String) return Foo;
end Base;
with Base;
package Client is
type Bar is new Foo;
-- At this point, the following declarations are
-- implicitly made:
--
-- function "="(L,R: Bar) return Boolean;
--
-- procedure Put(Item: bar);
-- function Value(Of_The_Image: String) return Bar;
--
end Client;
It is therefore not necessary to redefine these operations as skins. Note, however, that generic subprograms (such as passive iterators) are not derived along with other operations, and must therefore be re-exported as skins. Subprograms defined elsewhere than the specification containing the base type declaration are also not derivable, and must also be re-exported as skins.
Specify
initial values in object declarations, unless the object is self-initializing or
there is an implicit default initial value (for example, access types, task
types, records with default values for nondiscriminant fields).
The value assigned must be a real, meaningful value, not just any valueof the type. If the actual initial value is available, such as for example one of the input parameters, then assign it. If it is not possible to compute a meaningful value, then consider declaring the object later, or assign any "nil" value if available.
The name
"Nil" is meant as "Uninitialized" and it is used to declare
constants that can be used as a "unusable but known value" that can be
rejected in a controlled fashion by algorithms.
Whenever feasible, the Nil value should not be used for any other purpose than initialization, so that its appearance can always indicate an uninitialized variable error.
Note that it is not always possible to declare a Nil value for all types, especially modular types, such as an angle. In this case choose the less likely value.
Note that
code to initialize large records may be costly, especially if the record has
variants and if some initial value is nonstatic (or, more precisely, if the
value cannot be computed at compile time). It is sometimes more efficient to
elaborate once and for all an initial value (perhaps in the package defining the
type) and assign it explicitly:
R : Some_Record := Initial_Value_For_Some_Record;
Note:
Experience shows that uninitialized variables are one of the main sources of problems in porting code and one of the major sources of programming errors. This is aggravated when the development host tries to be "nice" to the programmer by providing default values for at least some of the objects (for example, type Integer on the Rational native compiler) or when the target system zeroes the memory before program loading (for example, on a DEC VAX). To achieve portability, always assume the worst.
Assigning an
initial value in the declaration can be omitted when it is costly and when it is
obvious that the object is assigned a value before being used.
Example:
procedure Schmoldu is
Temp : Some_Very_Complex_Record_Type;
-- initialized later
begin
loop
Temp := Some_Expression ...
...
Avoid the
use of literal values in the code.
Use constants (with a type) when the value defined is bound to a type. Otherwise, use named numbers, especially for all dimensionless values (pure values):
Earth_Radius : constant Meter := 6366190.7; -- In meters. Pi : constant := 3.141592653; -- No units.
Define
related constants with universal, static expressions:
Bytes_Per_Page : constant := 512; Pages_Per_Buffer : constant := 10; Buffer_Size : constant := Bytes_Per_Page * Pages_Per_Buffer; Pi_Over_2 : constant := Pi / 2.0;
This takes advantage of the fact that these expressions must be computed exactly at compile time.
Do not
declare objects with anonymous types. For more information see the Ada Reference Manual 3.3.1.
Maintainability is reduced, objects cannot be passed as parameters, and it often leads to type conflict errors.
Subprograms
can be declared as procedures or functions; here are some general criteria that
can be used to choose which form to declare.
Declare a function when:
Declare a procedure when:
Avoid giving
default values to generic formal parameters used for sizing structures (tables,
collections, etc.)
Write local
procedures with as few side effects as possible, and functions with no side
effects at all. Document the side effect.
Side effects are usually modifications of global variables, and may only be noticed when reading the body of the subprogram. The programmer may not be aware of side effects at the call site.
Passing in the required objects as parameters makes the code more robust, easier to understand and less dependent on its content.
This rule applies mainly to local subprograms: exported subprograms often require legitimate access to global variables in the package body.
Use
redundant parentheses to make compound expressions clearer.
The level of nesting of an expression is defined as the number of nested sets of parentheses required to evaluate an expression from left to right if the rules of operator precedence were ignored.
Limit the
level of nesting of expressions to four.
Record
aggregates should use named associations and should be qualified:
Subscriber.Descriptor'(Name => Subscriber.Null_Name,
Mailbox => Mailbox.Nil,
Status => Subscriber.Unknown,
...);
The use of a
when others is forbidden for record aggregates.
This is because, in contrast to arrays, records are naturally heterogeneous structures, and uniform assignment therefore is unreasonable.
Use simple
Boolean expressions in place of "if...then...else" statements for
simple predicates:
function Is_In_Range(The_Value: Value; The_Range: Range)
return Boolean is
begin
if The_Value >= The_Range.Min and The_Value <= The_Range.Max then return True;
end if;
end Is_In_Range;
It would be better to use the following:
function Is_In_Range(The_Value: Value; The_Range: Range)
return Boolean is
begin
return The_Value >= The_Range.Min
and The_Value <= The_Range.Max;
end Is_In_Range;
Complex expressions containing two or more if statements should not be changed in this manner if it affects readability.
Loop
statements should have names:
Forever: loop ... end loop Forever;
When a loop
has a name, any exit statement it contains should specify it.
Loops which
require a completion test at the beginning should use the "while" loop
form. Loops which require a completion test elsewhere should use the general
form and an exit statement.
Minimize the
number of exit statements in a loop.
In a
"for" loop that iterates oven an array, use the 'Range attribute
applied on the array object, rather than an explicit range or some other
subtype.
Move any
loop-independent code out of the loop. Although "code hoisting" is a
common compiler optimization, it cannot be done when the invariant code makes
calls to other compilation units.
Example:
World_Search:
while not World.Is_At_End(World_Iterator) loop
...
Country_Search:
while not Nation.Is_At_End(Country_Iterator) loop
declare
City_Map: constant City.Map := City.Map_Of
(The_City => Nation.City_Of(Country_Iterator),
In_Atlas => World.Country_Of(World_Iterator).Atlas);
begin
...
In the above code, the call to "World.Country_Of" is loop-independent (i.e., the country remains unchanged in the inner loop). However, in most cases, the compiler is prohibited from moving the call out of the loop, since the call may have side effects that can affect the program execution. The code will therefore execute unnecessarily each time through the loop.
The loop is more efficient and easier to understand and maintain if rewritten as:
Country_Search:
while not World.Is_At_End(World_Iterator) loop
declare
This_Country_Atlas: constant Nation.Atlas
:= World.Country_Of
(World_Iterator).Atlas;
begin
...
City_Search:
while not Nation.Is_At_End (The_City_Iterator) loop
declare
City.Map_Of (
The_City => Nation.City_Of
(Country_Iterator),
In_Atlas => This_Country_Atlas );
begin
...
Subprogram
and entry calls should use named associations.
However, if it is clear that the first (or only) parameter is the main focus of the operation (for example, a direct object of a transitive verb), the name can be omitted for this parameter only:
Subscriber.Delete (The_Subscriber => Old_Subscriber);
where Subscriber.Delete is the transitive verb, and Old_Subscriber is the direct object. The following expressions without the named association The_Subscriber => Old_Subscriber are acceptable:
Subscriber.Delete (Old_Subscriber);
Subscriber.Delete (Old_Subscriber,
Update_Database => True,
Expunge_Name_Set => False);
if Is_Administrator (Old_Subscriber) then ...
There are also cases where the meaning of parameters is so obvious that named association would just degrade legibility. This is true, for instance, when all parameters are of the same type and mode and have no default values:
if Is_Equal (X, Y) then ... Swap (U, B);
A when
others should not be used in case statements or in record type definitions
(for variants).
Not using a when others will help during the maintenance phase by making these constructs invalid whenever the discrete type definition is modified, forcing the programmer to consider what should be done to handle he modification. However it is tolerated when the selector is a large integer range.
Use a case
statement rather than a series of "elsif" when the branching condition
is a discrete value.
Subprograms
should have a single point of return.
Try to exit from subprograms at the end of the statement part. Functions should have a single return statement. Return statements sprinkled freely over a function body are akin to goto statements, making the code difficult to read and to maintain.
Procedures should have no return statements at all.
Multiple returns
can be tolerated only in very small functions, when all returns can be
seen simultaneously and when the code has a very regular structure:
function Get_Some_Attribute return Some_Type is
begin
if Some_Condition then
return This_Value;
else
return That_Other_Value;
end if;
end Get_Some_Attribute;
The use of goto
statements is restricted.
In defense of the "goto" statement;, it should be noted that the syntax of goto labels and the restricted conditions of the goto's use in Ada makes this statement not as harmful as might be thought, and in many cases it is preferable and more legible and meaningful than some equivalent constructs (a fake goto built with an exception, for instance).
When
manipulating arrays, do not assume that their index starts at 1. Use the
attributes 'Last, 'First, 'Range.
Define the
most common constrained subtype of your unconstrained types-records mostly-and
use those subtypes for parameters and return values to increase self-checking in
the client code:
type Style is (Regular, Bold, Italic, Condensed);
type Font (Variety: Style) is ...
subtype Regular_Font is Font (Variety => Regular);
subtype Bold_Font is Font (Variety => Bold);
function Plain_Version (Of_The_Font: Font) return Regular_Font;
procedure Oblique (The_Text : in out Text;
Using_Font : in Italic_Font);
...
The following guidelines are recommended:
Overload
subprograms.
Do make sure, however, when using the same identifier, that it is really implying the same kind of operation.
Avoid the
hiding of homograph identifiers in nested scopes.
This leads to confusion for the reader and potential risks in maintenance. Be aware also of the existence and scope of "for" loop control variables.
Do not
overload operations on subtypes, always on the type.
Contrary to what the naive reader may be led to believe, the overloading will apply to the base type and all its subtypes.
Example:
subtype Table_Page is Syst.Natural16 range 0..10; function "+"(Left, Right: Table_Page) return Table_Page;
The compiler looks for the base type and not the subtype of a parameter when matching subprograms. Therefore, in the above example, "+" is actually redefined for all Natural16 values in the current package, not just Table_Page. Thus any expression "Natural16 + Natural16" would now be mapped to a call to "+"(Table_Page, Table_Page), which would probably return the wrong result or produce an exception.
Minimize the
number of dependencies introduced by "with" clauses.
Where visibility is extended by the use of a "with" clause, the clause should cover as small a region of code as possible. Use a "with" clause only when necessary, ideally only on a body, or even on a large body stub.
Use interface packages to re-export low-level entities, thus avoiding visibly "with"-ing a large number of low-level packages. To do so, use derived types, renaming, skin subprograms, and, perhaps, predefined types such as strings (as is done with Environment command packages).
Use soft (weak) coupling between units by using generic formal parameters, rather than hard (strong) coupling by using "with" clauses.
Example: To export a Put procedure on a composite type, import as generic formals some procedure Put for its components, instead of directly withing Text_Io.
"Use"
clauses should not be used.
Avoiding "use" clauses as much as possible increases readability and legibility, provided this rule is adequately supported by naming conventions that make effective use of the context and by appropriate renaming. (See "Naming Conventions," above). It also helps prevent some visibility surprises, especially during the maintenance phase.
For a package defining a character type, a "use" clause is necessary in any compilation unit that needs to define string literals based on this character type:
package Internationalization is
type Latin_1_Char is (..., 'A', 'B', 'C', ..., U_Umlaut, ...);
type Latin_1_String is array (Positive range <>) of
Latin_1_Char;
end Internationalization ;
use Internationalization;
Hello : constant Latin_1_String := "Baba"
The absence of a "use" clause prevents the use of operators in infix form. Those can be renamed in the client unit:
function "=" (X, Y : Subscriber.Id) return Boolean
renames Subscriber."=";
function "+" (X, Y :Base_Types.Angle) return Base_Types.Angle
renames Base_Types."+";
Since the
absence of a "use" clause often leads to including the same set of
renamings in numerous client units, all those renamings can be factorized in the
defining package itself, by means of a package Operations nested in the defining
package. A "use" clause on package Operations is then recommended in
the client unit:
package Pack is
type Foo is range 1 .. 10;
type Bar is private;
...
package Operations is
function "+" (X, Y : Pack.Foo) return Pack.Foo
renames Pack."+";
function "=" (X, Y : Pack.Foo) return Boolean
renames Pack."=";
function "=" (X, Y : Pack.Bar) return Boolean
renames Pack."=";
...
end Operations;
private
...
end Pack;
with Pack;
package body Client is
use Pack.Operations; -- Makes ONLY Operations directly visible.
...
A, B : Pack.Foo; -- Still need prefix Pack.
...
A := A + B ; -- Note that "+" is directly
-- visible.
Package Operations should always have this name and should always be placed at the bottom of the visible part of the defining package. The "use" clause should be placed only where necessary-that is, it should be placed only in the body of Client if no operation is used in the specification, which is often the case.
with Defs;
package Client is
...
package Inner is
use Defs;
...
end Inner; -- The scope of the use clause ends here.
...
end Client;
declare
use Special_Utilities;
begin
...
end; -- The scope of the use clause ends here.
Use renaming
declarations.
Renaming is recommended in conjunction with the restriction on "use" clauses to make the code easier to read. When a unit with a very long name is referred to several times, providing a very short name for it will enhance legibility:
with Directory_Tools;
with String_Utilities;
with Text_Io;
package Example is
package Dt renames Directory_Tools;
package Su renames String_Utilities;
package Tio renames Text_Io;
package Dtn renames Directory_Tools.Naming;
package Dto renames Directory_Tools.Object;
...
The choice
of short names should be consistent throughout the project, in keeping with the
minimal-surprise principle. The way to achieve this is to provide the short name
in the package itself:
package With_A_Very_Long_Name is package Vln renames
With_A_Very_Long_Name;
...
end
with With_A_Very_Long_Name;
package Example is package Vln renames With_A_Very_Long_Name;
-- From here on Vln is an abbreviation.
Be aware that a package renaming gives visibility only to the visible part of the renamed package.
Imported
package renamings must be grouped at the beginning of the declarative part and
alphabetically sorted.
Renaming can
be used locally wherever it will enhance legibility (there is no runtime penalty
for doing so). Types can be renamed as subtypes without restriction.
As shown in the section on comments, renaming often provides an elegant and maintainable way to document the code-for example, to give a simple name to some complex object or to refine locally the meaning of a type. The scope of the renaming identifier should be chosen to avoid introducing confusion.
Renaming
exceptions allows exceptions to be factorized among several units-for example,
among all instantiations of a generic package. Note that, in a package deriving
a type, exceptions potentially raised by the derived subprograms should be
re-exported together with the derived type to avoid the clients having to
"with" the original package:
with Inner_Defs; package Exporter is ... procedure May_Raise_Exception; -- Raises exception Inner_Defs.Bad_Schmoldu when ... ... Bad_Schmoldu : exception renames Inner_Defs.Bad_Schmoldu; ...
Renaming
subprograms with different default values for "in" parameters may
allow simple code factorization and enhance legibility:
procedure Alert (Message : String;
Beeps : Natural);
procedure Bip (Message : String := "";
Beeps : Natural := 1)
renames Alert;
procedure Bip_Bip (Message : String := "";
Beeps : Natural := 2)
renames Alert;
procedure Message (Message : String;
Beeps : Natural := 0)
renames Alert;
procedure Warning (Message : String;
Beeps : Natural := 1)
renames Alert;
Avoid using
the name of the renamed entity (the old name) within the immediate scope of the
renaming declaration; use only the identifier or operator symbol introduced by
the renaming declaration (the new name).
For many years there has been a "use" clause controversy in the Ada community, verging sometimes on a religious war. Both parties have used various arguments that often do not scale well to large projects or examples that are far too unrealistic-or deliberately unfair.
Advocates of the "use" clause claim that it increases legibility, and they provide examples of especially unreadable, long, and redundant names, which would benefit from being renamed if used several times. They also claim that an Ada compiler can resolve overloading, which is true, but a human being immersed in a large Ada program cannot do overloading resolution as reliably as a compiler, and certainly not as fast. They claim that sophisticated APSEs, such as the Rational Environment, make the explicit fully qualified names useless; but this is not true-the user should not have to press [Definition] for each identifier he or she is not sure of. The user should not have to guess, but should be able to see immediately which objects and which abstractions are used. Rosen advocates of the "use" clause deny its potential dangers in program maintenance and suggest giving an F grade to the programmer who creates such risks; we think that fully qualified names eliminate that risk.
If the methods suggested above to alleviate the impact of the restriction on "use" clauses seem to require too much typing, consider the conclusion of Norman H. Cohen: "Any time saved when a program is being typed will be lost many times over when the program is reviewed, debugged, and maintained."
Finally, it has been shown that in large systems the absence of "use" clauses improves compilation time by reducing lookup overhead in symbol tables.
The reader interested in learning more about the use clause controversy can consult the following sources:
D. Bryan, "Dear Ada," Ada Letters, 7, 1, January-February 1987, pp. 25-28.
J. P. Rosen, "In Defense of the Use Clause," Ada Letters, 7, 7, November-December 1987, pp. 77-81.
G. O. Mendal, "Three Reasons to Avoid the Use Clause," Ada Letters, 8, 1, January-February 1988, pp. 52-57.
R. Racine, "Why the Use Clause Is Beneficial," Ada Letters, 8, 3, May-June 1988, pp. 123-127.
N. H. Cohen, Ada as a Second Language, McGraw-Hill (1986), pp. 361-362.
M. Gauthier, Ada-Un Apprentissage, Dunod-Informatique, Paris (1989), pp. 368-370.]
There are two fundamental ways to decompose a large "logical" package, resulting from an initial design phase into several smaller Ada library units that are easier to manage, compile, maintain, and understand:
a) The nested decomposition
This approach emphasizes the use of Ada subunits and/or subpackages. The major subprograms, task bodies, and inner package bodies are systematically separated. The process is recursively repeated within those subunits/subpackages.
b) The flat decomposition
The logical package is decomposed into a network of smaller packages that are interconnected by "with" clauses, and the original logical package is mostly a re-exporting skin (or a design artifact that no longer even exists).
Each approach has its advantages and disadvantages. The nested decomposition requires less code to be written and leads to simpler naming (many identifiers do not need prefixing); and, on the Rational Environment at least, the structure is very visible in the library image and the structure is easier to transform (commands Ada.Make_Separate, Ada.Make_Inline). The flat decomposition often leads to less recompilation and better or cleaner structure (particularly at subsystem boundaries); it also fosters reuse. It is also easier to manage with automatic recompilation tools and configuration management. However, with the flat structure, there is a greater risk of violating the original design by "with"-ing some of the lower-level packages that have been created in the decomposition.
The level of
nesting should be limited to three for subprograms, and to two for packages; do
not nest packages within subprograms.
package Level_1 is
package Level_2 is
package body Level_1 is
procedure Level_2 is
procedure Level_3 is
Use body
stubs for nested units ("separate bodies") when one of the following occurs:
The
declarative part of a package specification contains declarations that should be
arranged in the following sequence:
1) Renaming declaration for the package itself
2) Renaming declarations for imported entities
3) "Use" clauses
4) Named numbers
5) Type and subtype declarations
6) Constants
7) Exception declarations
8) Exported subprogram specifications
9) Nested packages, if any
10) Private part.
For a
package that introduces several major types, it may be better to have several
sets of related declarations:
5) Type and subtype declarations for A
6) Constants
7) Exception declarations
8) Exported subprogram specifications for operations on A
5) Type and subtype declarations for B
6) Constants
7) Exception declarations
8) Exported subprogram specifications for operations on B
Etc.
When the
declarative part is large (>100 lines) use small comment blocks to delimit
the various sections.
The
declarative part of a package body declarations contains declarations that
should be arranged in the following sequence:
1) Renaming declarations (for imported entities)
2) "Use" clauses
3) Named numbers
4) Type and subtype declarations
5) Constants
6) Exception declarations
7) Local subprogram specifications
8) Local subprogram bodies
9) Exported subprogram bodies
10) Nested package bodies, if any.
Other
declarative parts, such as in subprogram bodies, task bodies and block
statements follow the same general pattern.
Use one
"with" clause per imported library unit. Sort the with clauses in
alphabetical order. If a "use" clause on a "with"-ed unit is
appropriate, then it should immediately follow the corresponding
"with" clause. See below for the pragma Elaborate.
Do not rely
on the order of elaboration of library units to achieve any specific effect.
Each Ada implementation is free to choose a strategy to compute the elaboration order, provided it satisfies the very simple rules stated in the Ada Reference Manual [ISO87]. Some implementations use smarter strategies than others (such as elaborating the bodies as soon as feasible after the corresponding spec), and some implementations do not bother to be this smart (especially for generic instantiations), leading to very severe portability problems.
There are three main sources for the infamous "access before elaboration" error during program elaboration (which should normally raise the Program_Error exception):
task type T; type T_Ptr is access T; SomeT : T_Ptr := new T; -- Access before elaboration.
To avoid
problems in porting applications from one Ada compiler to another, the
programmer should either eliminate the problems by restructuring the code (which
is not always possible) or explicitly take control of elaboration order by means
of pragma Elaborate, using the following strategy:
In the context clause of a unit Q, a pragma Elaborate should be applied to each unit P that appears in a "with" clause:
Moreover, if P exports a type T such that the elaboration of objects of type T calls a function in package R, then the context clause of Q should contain:
with R; pragma Elaborate (R);
even if there are no direct references to R in Q!
Practically, it may be easier (but not always possible) to state the rule that package P should include:
with R; pragma Elaborate (R);
The package Q must simply carry:
with P; pragma Elaborate (P);
therefore providing the right elaboration order by transitivity.
Restrict the
use of tasks.
Tasks are a very powerful feature, but they are delicate to use. Large overhead in space and time may be associated with the injudicious use of tasks. Small changes to some part of the system may completely jeopardize the liveness of a set of tasks, leading to starvation and/or deadlocks. Testing and debugging tasking programs is difficult. Therefore the use of tasks, their placement, and their interaction is a project-level decision. Tasks cannot be used in a hidden way or written by inexperienced programmers. The tasking model of an Ada program needs to be made visible and understandable.
Unless there is effective support from parallel hardware, tasks should be introduced only when concurrency is truly necessary. This is the case when expressing actions that depend on time: periodic activities or introduction of time-outs, or actions that depend on an external event such as an interrupt or the arrival of an external message. Tasks also need to be introduced to decouple other activities, such as: buffering, queuing, dispatching, and synchronizing access to common resources.
Specify the
task stack size with a 'Storage_Size length clause.
For the same reasons and in the same circumstances that led to the requirement that collections have length clauses ("Access Types" section, above), the size of a task should be specified in cases where memory is a precious resource. To do so, always declare tasks of an explicitly declared type (since the length clause can be applied only to a type). A function call maybe used to dynamically size the stack.
Note: It may be very difficult to guess how much stack each task requires. To facilitate this, the runtime system can be instrumented with a "high-water mark" mechanism.
Use an
exception handler in the body of a task to avoid or at least report the
unexplained death of a task.
Tasks that do not handle exceptions die-usually silently. If at all feasible, try to report the nature of the death, especially Storage_Error. This will allow fine-tuning the stack size. Note that this requires allocation (primitive new) to be encapsulated in a subprogram that re-exports an exception other than Storage_Error.
Create tasks
during program elaboration.
For the same reasons and in the same circumstances that led to the requirement that collections be allocated during program elaboration ("Access Types" section, above), the whole application tasking structure should be created very early at program startup. It is better to have the program not start at all because of memory exhaustion than to die a couple of days later.
In subsequent rules, a distinction is made between service tasks and application tasks. Service tasks are small and algorithmically simple tasks that are used to provide the "glue" between application-related tasks. Examples of service tasks (or intermediary tasks) include buffers, transporters, relays, agents, monitors, and so on that usually provide synchronization, decoupling, buffering, and waiting services. Application tasks, as the name conveys, are more directly related to the primary functions of the application.
Avoid hybrid
tasks: application tasks should be made pure callers; service tasks should be
made pure callees.
A pure callee is a task that contains only accept statements or selective waits and no entry calls.
Avoid
circularities in the graph of entry calls.
This will considerably reduce the risk of deadlocks. Avoid circularities at least in the system's steady-state, if they cannot be avoided completely. These two rules also make the structure easier to understand.
Restrict the
use of shared variables.
Be particularly aware of hidden shared variables-that is, variables that are hidden in package bodies, for instance, and accessed by primitives visible to several tasks. Shared variables can be used in extreme cases for synchronization of access to common data structures, when the cost of rendezvous is too high. Check whether pragma Shared is effectively supported.
Restrict the
use of abort statements.
The abort statement is universally recognized as one of the most dangerous and harmful primitives of the language. Its usage to terminate tasks unconditionally (and almost asynchronously) makes it almost impossible to reason about the behavior of a given tasking structure. However, there are very limited circumstances in which an abort statement is necessary.
Example: Some low-level services are provided that have no facility for time-out. The only way to introduce a time-out is to have the service provided by some auxiliary agent task, to wait (with a time-out) for a reply from the agent, and then to kill the agent with an abort if the service has not been provided within the delay time.
An abort is tolerable when it can be demonstrated that only the aborter and the abortee can be affected-for example, when no other task can possibly call the aborted task.
Restrict the
use of delay statements.
Arbitrary suspension of a task may lead to severe scheduling problems, which are hard to track down and correct.
Restrict the
use of attributes 'Count, 'Terminated, and 'Callable.
Attribute 'Count should be used only as a rough indication, and scheduling decisions should not be based on its value being zero or not, since the actual number of waiting tasks can change between the time the attribute is evaluated and the time its value is used.
Use conditional entry calls (or the equivalent construct with accept) to reliably check the absence of waiting tasks.
select
The_Task.Some_Entry;
else
-- do something else
end select;
This is preferable to the following:
if The_Task.Some_Entry'Count > 0 then
The_Task.Some_Entry;
else
-- do something else
end if;
Attribute 'Terminated is meaningful only when it yields True and 'Callable when it yields False, thereby considerably limiting their usefulness. They should not be used to provide synchronization between tasks during system shutdown.
Restrict the
use of priorities.
Priorities in Ada have a limited impact on scheduling. In particular, priorities of tasks waiting on entries are not taken into account for ordering the entry queues or for selecting the entry to serve in a selective wait. This may lead to priority inversion (see [GOO88]) Priorities are used by the scheduler only to select the next task to run among the tasks ready to run. Because of the risk of priority inversion, do not rely on priorities for mutual exclusion.
By using families of entries, it is possible to split the entry queue into several subqueues, and with this it is often possible to introduce an explicit concept of urgency.
If priorities are not necessary, do not assign any priority to any task.
Once a
priority is assigned to one task, assign a priority to all tasks in the
application.
This rule is necessary because the priorities of tasks without a pragma Priority are undefined.
For
portability, keep the number of priority levels small.
The range of the subtype System.Priority is implementation-defined, and experience shows that the actual range available varies enormously from system to system. Moreover, it is a good idea to centrally define the priorities, giving them names and definitions, rather than using integer literals in all tasks. Having such a central System_Priorities package eases portability and, together with the previous rule, allows easy location of all task specifications.
To avoid
drift in cyclic tasks, program the delay statement to take into account
processing time, overhead, and task preemption:
Next_Time := Calendar.Clock;
loop
-- Do the job.
Next_Time := Next_Time + Period;
delay Next_Time - Clock;
end loop;
Note that Next_Time - Clock may be negative, indicating that the cyclic task is running late. It may be possible to drop one cycle.
To guarantee
schedulability, assign priorities to cyclic tasks according to the Rate
Monotonic Scheduling Algorithm-that is, the highest priority to the most
frequent task. (See [SHA90] for more details.)
Assign a
higher priority to very fast intermediary servers: monitors, buffers.
But then make sure that these servers do not block themselves by rendezvousing with other tasks. Document this priority in the code so that it can be respected during program maintenance.
To minimize
the effect of "jitter," rely on time-stamping input samples or output
data, rather than on the period itself.
Avoid busy
wait (polling).
Make sure tasks wait with select or entry calls, or are delayed, rather than furiously checking for something to do.
For each
rendezvous, make sure that at least one side is waiting and that only one side
has a conditional entry call or timed entry call or waits.
Otherwise, notably in loops, there is the risk of the code running into a race condition, highly similar in result to a busy wait. This may be aggravated by poor use of priorities.
When
encapsulating tasks, be sure to leave some of their special characteristics
highly visible.
If entry calls are hidden in subprograms, make sure the reader of the specification of those subprograms is aware that the call to this subprogram may block. Additionally, specify whether the wait is bounded; if so, provide some estimate of the upper bound. Use a naming convention to indicate the potential wait ("Subprograms" section, above).
If the elaboration of a package, the call of a subprogram, or the instantiation of a generic unit activates a task, make this fact visible to the client:
package Mailbox_Io is
-- This package elaborates an internal Control task
-- that synchronizes all access to the external
-- mailbox
procedure Read_Or_Wait
(Name: Mailbox.Name; Mbox: in out Mailbox.Object);
--
-- Blocking (unbounded wait).
Do not rely
on any specific order for entry selection in a selective wait.
If some fairness is required in picking up tasks queued in entries, achieve this by explicitly checking the queues with no wait in the desired order and then wait on all entries. Do not use 'Count.
Do not rely
on any specific activation order for tasks elaborated in the same declarative
part.
If a specific startup ordering is sought, this should be achieved by making rendezvous with special startup entries.
Implement
tasks to terminate normally.
Unless the nature of the application requires that tasks, once activated, run forever, tasks should terminate, either by reaching normal completion or through a terminate alternative. This may be impossible to achieve for tasks whose master is a library-level package, since the Ada Reference Manual does not specify under which condition they should terminate.
If the master-dependent structure does not allow clean termination, then tasks should provide and wait for special shutdown entries, which are called during system shutdown.
The general philosophy is to use exceptions only for errors: logic and programming errors, configuration errors, corrupted data, resource exhaustion, etc. The general rule is that the systems in normal condition and in the absence of overload or hardware failure should not raise any exceptions.
Use
exceptions to handle logic and programming errors, configuration errors,
corrupted data, resource exhaustion. Report exceptions by the appropriate
logging mechanism as early as possible, including at the point of raise.
Minimize the
number of exceptions exported from a given abstraction.
In large systems, having to handle a large number of exceptions at each level makes the code difficult to read and to maintain. Sometimes the exception processing dwarfs the normal processing.
There are several ways to minimize the number of exceptions:
Do not
propagate exceptions not specified in the design.
Avoid a when
others alternative in exception handlers, unless the caught exception is
raised again.
This allows some local housekeeping without interfering with exceptions that cannot be handled at this level:
exception
when others =>
if Io.Is_Open (Local_File) then
Io.Close (Local_File);
end if;
raise;
end;
Another place where a when others alternative may be used is at the bottom of a task body.
Do not use
exceptions for frequent, anticipated events.
There are several inconveniences in using exceptions to represent conditions that are not clearly errors:
For instance, do not use an exception as some form of extra value returned by a function (like Value_Not_Found in a search); use a procedure with an "out" parameter, or introduce a special value meaning Not_Found, or pack the returned type in a record with a discriminant Not_Found.
Do not use
exceptions to implement control structures.
This is a special case of the previous rule: exceptions should not be used as a form of "goto" statement.
When
catching predefined exceptions, place the handler in a very small frame
surrounding the construct raising it.
Predefined exceptions like Constraint_Error, Storage_Error, and so on can occur in many places. If one such exception needs to be caught for some specific reason, the handler must be as limited in scope as possible:
begin
Ptr := new Subscriber.Object;
exception
when Storage_Error =>
raise Subscriber.Collection_Overflow;
end;
Terminate
exception handlers in functions with either a "return" statement or a
"raise" statement. Otherwise the Program_Error exception will be
raised in the caller.
Restrict the
suppressing of checks.
With today's Ada compilers, the potential reductions in code size and increases in performance obtained by suppressing checks have become marginal. Therefore, suppressing checks should be restricted to very limited pieces of code that have been identified (by doing measurements) as performance bottlenecks; it should never be applied widely to a whole system.
As a corollary, do not add extra explicit range and discriminant checking just for the improbable case that someone will decide later to suppress checks. Rely on Ad's built-in constraint-checking facilities.
Do not
propagate exceptions out of the scope of their declaration.
This will make it impossible for client code to explicitly handle the exception, other than with a when others alternative, which may not be specific enough.
A corollary to this rule is: when re-exporting a type by derivation, think of re-exporting the exceptions that the derived subprograms may raise-by renaming, for instance. Otherwise, the clients will have to "with" the original defining package.
Always
handle Numeric_Error and Constraint_Error together.
The Ada Board has decided that all circumstances that would have raised Numeric_Error should raise Constraint_Error instead.
Make sure
status codes have an appropriate value.
When using status code returned by subprograms as an "out" parameter, always make sure a value is assigned to the "out" parameter by making this the first executable statement in the subprogram body. Systematically make all statuses a success by default or a failure by default. Think of all possible exits from the subprogram, including exception handlers.
Perform
safety checks locally; do not expect your client to do so.
That is, if a subprogram might produce erroneous output unless given proper input, install code in the subprogram to detect and report invalid input in a controlled manner. Do not rely on a comment that tells the client to pass proper values. It is virtually guaranteed that sooner or later that comment will be ignored, resulting in hard-to-debug errors if the invalid parameters are not detected.
For further information, see [KR90b].
This section deals with Ada features that are a priori non-portable. They are defined in chapter 13 of the Reference Manual for the Ada Programming Language [ISO87], and the compiler-specific features are described in the "Appendix F" provided by the Ada compiler vendors.
Study
carefully Appendix F of the Ada Reference Manual (and conduct small experiments
to ensure that it is well understood).
Restrict the
use of representation clauses.
Representation clauses are not supported uniformly from implementation to implementation. Their use contains many traps. Therefore, they should not be used freely in a system.
Representation clauses should do the following:
Representation clauses can be avoided in the following kinds of situations:
Example:
Replace:
type Foo is (Bla, Bli, Blu, Blo); for Foo use (Bla => 1, Bli =>3, Blu => 4, Blo => 5);
type Foo is (Invalid_0, Bla, Invalid_2, Bli, Blu, Blo);
Group types
that have representation clauses into packages clearly identified as containing
implementation-dependent code.
Never assume
a specific order in record layout.
In a record
representation clause, always specify the placement of all discriminants, and do
so before specifying any components in the variants.
Avoid
alignment clauses.
Trust the compiler to do a good job; it knows the target alignment constraints. programmer's use of alignment clauses is likely to lead to alignment conflicts later.
Be aware of
the existence of compiler-generated fields in unconstrained composite types:
in records: offset of dynamic fields, variant clause index, constrained bit, and so on
in arrays: dope vectors.
Refer to the Appendix F for the compiler for details. Do not rely on what is written in chapter 13 of the Ada Reference Manual [ISO87].
Restrict the
use of Unchecked_Conversion.
The extent of support for Unchecked_Conversion varies greatly from one Ada compiler to another, and its precise behavior may be slightly different, especially when applied to composite types and access types.
In an
instantiation of Unchecked_Conversion, ensure that both source and target types
are constrained and have the same size.
This is the only way to achieve some limited portability and to avoid running into problems with implementation-added information such as dope vectors. One way to make sure both types have the same size is to "wrap" them in a record type with a record representation clause.
One way to make the type constrained is to do the instantiation within a "skin" function, where the constraint is computed beforehand.
Do not apply
Unchecked_Conversion to access values or tasks.
Not only is this not supported by all systems (for example, the Rational native compiler), but also it should not be assumed that:
We recapitulate here the most important things to watch for:
):)This document is derived directly from Ada Guidelines: Recommendations for Designer and Programmers, Application Note #15, Rev. 1.1, Rational, Santa Clara, Ca., 1990. [KR90a]. However, many different sources have contributed to its elaboration.
BAR88 B. Bardin & Ch. Thompson, "Composable Ada Software Components and the Re-export Paradigm", Ada Letters, VIII, 1, Jan.-Feb. 1988, p.58-79.
BOO87 E. G. Booch, Software Components with Ada, Benjamin/Cummings (1987)
BOO91 Grady Booch: Object-Oriented Design with Applications, Benjamin-Cummings Pub. Co., Redwood City, California, 1991, 580p.
BRY87 D. Bryan, "Dear Ada," Ada Letters, 7, 1, January-February 1987, pp. 25-28.
COH86 N. H. Cohen, Ada as a Second Language, McGraw-Hill (1986), pp. 361-362.
EHR89 D. H. Ehrenfried, Tips for the Use of the Ada Language, Application Note #1, Rational, Santa Clara, Ca., 1987.
GAU89 M. Gauthier, Ada-Un Apprentissage, Dunod-Informatique, Paris (1989), pp. 368-370.
GOO88John B. Goodenough and Lui Sha: "The Priority Ceiling Protocol," special issue of Ada Letters, Vol., Fall 1988, pp. 20-31.
HIR92 M. Hirasuna, "Using Inheritance and Polymorphism with Ada in Government Sponsored Contracts", Ada Letters, XII, 2, March/April 1992, p.43-56.
ISO87 Reference Manual for the Ada Programming Language, International Standard ISO 8652:1987.
KR90a Ph. Kruchten, Ada Guidelines: Recommendations for Designer and Programmers, Application Note #15, Rev. 1.1, Rational, Santa Clara, Ca., 1990.
KR90b Ph. Kruchten, "Error-Handling in Large, Object-Based Ada Systems," Ada Letters, Vol. X, No. 7, (Sept. 1990), pp. 91-103.
MCO93 Steve McConnell, Code Complete-A Practical Handbook of Software Construction, Microsoft® Press, Redmond, WA, 1993, 857p.
MEN88 G. O. Mendal, "Three Reasons to Avoid the Use Clause," Ada Letters, 8, 1, January-February 1988, pp. 52-57.
PER88 E. Perez, "Simulating Inheritance with Ada", Ada letters, VIII, 5, Sept.-Oct. 1988, p. 37-46.
PLO92 E. Ploedereder, "How to program in Ada 9X, Using Ada 83", Ada Letters, XII, 6, November 1992, pp. 50-58.
RAC88 R. Racine, "Why the Use Clause Is Beneficial," Ada Letters, 8, 3, May-June 1988, pp. 123-127.
RAD85 T. P. Bowen, G. B. Wigle & J. T. Tsai, Specification of Software Quality Attributes, Boeing Aerospace Company, Rome Air Development Center, Technical Report RADC-TR-85-37 (3 volumes).
ROS87 J. P. Rosen, "In Defense of the Use Clause," Ada Letters, 7, 7, November-December 1987, pp. 77-81.
SEI72 E. Seidewitz, "Object-Oriented Programming with Mixins in Ada", Ada Letters, XII, 2, March/April 1992, p.57-61.
SHA90 Lui Sha and John B. Goodenough: "Real-Time Scheduling Theory and Ada," Computer, Vol. 23, #4 (April 1990), pp. 53-62.)
SPC89 Software Productivity Consortium: Ada Quality and Style-Guidelines for the Professional Programmer, Van Nostrand Reinhold (1989)
TAY92 W. Taylor, Ada 9X Compatibility Guide, Version 0.4, Transition Technology Ltd., Cwmbran, Gwent, U.K., Nov. 1992.
WIC89 B. Wichman: Insecurities in the Ada Programming Language, Report DITC137/89, National Physical Laboratory (UK), January 1989.
Most terms used in this document are defined in Appendix D of the Reference Manual for the Ada Programming Language, [ISO87]. Additional terms are defined here:
ADL: Ada as a Design Language; refers to the way Ada is used to express aspects of a design; a.k.a. PDL, or Program Design Language.
Environment: The Ada software development environment in use.
Library switch: In the Rational Environment, a compilation option that applies to a whole program library.
Model world: In the Rational Environment, a special library that is used to capture uniform project-wide library switch settings.
Mutable: Property of a record whose discriminants have default values; an object of a mutable type can be assigned any value of the type, even values that make it change its discriminants, hence its structure.
Skin: A subprogram whose body acts solely as a relay. It ideally contains only one statement: a call to another subprogram, with an identical set of parameters, or parameters that convertible to and from the parameter.
PDL: Program Design Language.