Ada '83 Quality and Style:

Guidelines for Professional Programmers

Copyright 1989, 1991,1992 Software Productivity Consortium, Inc., Herndon, Virginia.

CHAPTER 4: Program Structure

Chapter 4 Summary

In this section... 4.1 high-level structure 4.2 visibility 4.3 exceptions

4.1 high-level structure

• Place the specification of each library unit package in a separate file from its body.
• Create an explicit specification, in a separate file, for each library unit subprogram.
• Use subunits for the bodies of large units which are nested in other units.
• Place each subunit in a separate file.
• Use a consistent file naming convention.
• Use subprograms to enhance abstraction.
• Restrict each subprogram to the performance of a single action.
• Use a function when the subprogram's primary purpose is to provide a single value.
• Minimize the side effect of a function.
• Use packages for information hiding.
• Use packages with private types for abstract data types.
• Use packages to model abstract entities appropriate to the problem domain.
• Use packages to group together related type and object declarations (e.g., common declarations for two or more library units).
• Use packages to group together related program units for configuration control or visibility reasons.
• Encapsulate machine dependencies in packages. Place a software interface to a particular device in a package to facilitate a change to a different device.
• Place low-level implementation decisions or interfaces in subprograms within packages.
• Use packages and subprograms to encapsulate and hide program details that may change.
• Make each package serve a single purpose.
• Use packages to group functionally related data, types, and subprograms.
• Avoid collections of unrelated objects and subprograms.
• Avoid putting variables in package specifications.
• Use tasks to model abstract, asynchronous entities within the problem domain.
• Use tasks to control or synchronize access to tasks or other asynchronous entities (e.g., asynchronous I/O, peripheral devices, interrupts).
• Use tasks to define concurrent algorithms for multiprocessor architectures.
• Use tasks to perform concurrent, cyclic, or prioritized activities.

4.2 visibility

• Put only what is needed for the use of a package into its specification.
• Minimize the number of declarations in package specifications.
• Do not include extra operations simply because they are easy to build.
• Minimize the context (with) clauses in a package specification.
• Reconsider subprograms which seem to require large numbers of parameters.
• Do not manipulate global data within a subprogram or package merely to limit the number of parameters.
• Avoid unnecessary visibility; hide the implementation details of a program unit from its users.
• Nest package specifications within another package specification only for grouping operations, hiding common implementation details, or presenting different views of the same abstraction.
• Restrict the visibility of program units as much as possible by nesting them inside other program units and hiding them inside package bodies.
• Minimize the scope within which with clauses apply.
• Only with those units directly needed.
• Carefully consider encapsulation of tasks.

4.3 exceptions

• Declare a different exception name for each error that the user of a unit can make.
• Declare a different exception name for each unavoidable and unrecoverable internal error which can occur in a unit.
• Do not borrow an exception name from another context.
• Export (declare visibly to the user) the names of all exceptions which can be raised.
• In a package, document which exceptions can be raised by each subprogram and task entry.
• Do not raise exceptions for internal errors which can be avoided or corrected within the unit.
• Do not raise the same exception to report different types of errors which are distinguishable by the user of the unit.
• Provide interrogative functions which allow the user of a unit to avoid causing exceptions to be raised.
• When possible, avoid changing state information in a unit before raising an exception.
• Catch and convert or handle all predefined and compiler-defined exceptions at the earliest opportunity.
• Do not explicitly raise predefined or implementation-defined exceptions.
• Never let an exception propagate beyond its scope.