Ada '83 Quality and Style:

Guidelines for Professional Programmers

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

CHAPTER 8: Reusability

Chapter 8 Summary

8.1 understanding and clarity

• Select the least restrictive names possible for reusable parts and their identifiers.
• Select the generic name to avoid conflicting with the naming conventions of instantiations of the generic.
• Use names which indicate the behavioral characteristics of the reusable part, as well as its abstraction.
• Do not use any abbreviations in identifier or unit names.
• Document the expected behavior of generic formal parameters just as any package specification is documented.

8.2 robustness

• Use named numbers and static expressions to allow multiple dependencies to be linked to a small number of symbols.
• Use unconstrained array types for array formal parameters and array return values.
• Make the size of local variables depend on actual parameter size where appropriate.
• Minimize the number of assumptions made by a unit.
• For assumptions which cannot be avoided, use types to automatically enforce conformance.
• For assumptions which cannot be automatically enforced by types, add explicit checks to the code.
• Document all assumptions.
• Beware of using subtypes as type marks when declaring generic formal objects of type in out.
• Beware of using subtypes as type marks when declaring parameters or return values of generic formal subprograms.
• Use attributes rather than literal values.
• Be careful about overloading the names of subprograms exported by the same generic package.
• Within a specification, document any tasks that would be activated by with'ing the specification and by using any part of the specification.
• Document which generic formal parameters are accessed from a task hidden inside the generic unit.
• Propagate exceptions out of reusable parts. Handle exceptions within reusable parts only when you are certain that the handling is appropriate in all circumstances.
• Propagate exceptions raised by generic formal subprograms after performing any cleanup necessary to the correct operation of future invocations of the generic instantiation.
• Leave state variables in a valid state when raising an exception.
• Leave parameters unmodified when raising an exception.

8.3 adaptability

• Provide complete functionality in a reusable part or set of parts. Build in complete functionality, including end conditions, even if some functionality is not needed in this application.
• More specifically, provide initialization and finalization procedures for every data structure that may contain dynamic data.
• Use generic units to avoid code duplication.
• Parameterize generic units for maximum adaptability.
• Reuse common instantiations of generic units, as well as the generic units themselves.
• Use generic units to encapsulate algorithms independently of data type.
• Use abstract data types in preference to abstract data objects.
• Use generic units to implement abstract data types independently of their component data type.
• Provide iterators for traversing complex data structures within reusable parts.
• Provide both active and passive iterators.
• Protect the iterators from errors due to modification of the data structure during iteration.
• Document the behavior of the iterators when the data structure is modified during traversal.
• Use limited private (not private) for generic formal types, explicitly importing assignment and equality operations if required.
• Export the least restrictive type that maintains the integrity of the data and abstraction while allowing alternate implementations.
• Use mode in out rather than out for parameters of a generic formal subprogram, when the parameters are of an imported limited type.

8.4 independence

• Minimize with clauses on reusable parts, especially on their specifications.
• Use generic parameters instead of with statements to reduce the number of context clauses on a reusable part.
• Use generic parameters instead of with statements to import portions of a package rather than the entire package.
• For nongenerics named in a context clause, avoid pragma Elaborate.
• Use a pragma Elaborate for generics named in a context clause.
• Avoid pragma Priority in tasks hidden in reusable parts.
• Create families of generic or other parts with similar specifications.
• Structure reusable code to take advantage of dead code removal by the compiler.
• Write table-driven reusable parts where possible and appropriate.