------------------------------------------------------------------------
     -- AUTOLAYOUT
     -- Purpose:
     --   This package computes positional information for nodes and arcs
     --   of a directed graph.  It encapsulates a layout algorithm which is
     --   designed to minimize the number of crossing arcs and to emphasize
     --   the primary direction of arc flow through the graph.
     -- Effects:
     --   - The expected usage is:
     --     1. Call Define for each node and arc to define the graph.
     --     2. Call Layout to assign positions to all nodes and arcs.
     --     3. Call Position_Of for each node and arc to determine the
     --        assigned coordinate positions.
     --   - Layout can be called multiple times, and recomputes the
     --     positions of all currently defined nodes and arcs each time.
     --   - Once a node or arc has been defined, it remains defined until
     --     Clear is called to delete all nodes and arcs.
     -- Performance:
     --   This package has been optimized for time, in preference to space.
     --   Layout times are on the order of N*log(N) where N is the number
     --   of nodes, but memory space is used inefficiently.
     ------------------------------------------------------------------------
     package Autolayout is
        ...
        ---------------------------------------------------------------------
        -- Define
        -- Purpose:
        --   This procedure defines one node of the current graph.
   -- Exceptions:
        --   Node_Already_Defined
        ---------------------------------------------------------------------
        procedure Define
              (New_Node : in     Node);
        ---------------------------------------------------------------------
        -- Layout
        -- Purpose:
        --   This procedure assigns coordinate positions to all defined
        --   nodes and arcs.
        -- Exceptions:
        --   None.
        ---------------------------------------------------------------------
        procedure Layout;
        ---------------------------------------------------------------------
        -- Position_Of
        -- Purpose:
       --   This function returns the coordinate position of the
        --   specified node.  The default position (0,0) is returned if no
        --   position has been assigned yet.
        -- Exceptions:
        --   Node_Not_Defined
        ---------------------------------------------------------------------
        function Position_Of (Current : in     Node)
              return Position;
        ...
     end Autolayout;

rationale

The purpose of a header comment on the specification of a program unit is to help the user understand how to use the program unit. From reading the program unit specification and header, a user should know everything necessary to use the unit. It should not be necessary to read the body of the program unit. Therefore, there should be a header comment on each program unit specification, and each header should contain all usage information not expressed in the specification itself. Such information includes the units' effects on each other and on shared resources, exceptions raised, and time/space characteristics. None of this information can be determined from the Ada specification of the program unit.

When you duplicate information in the header that can be readily obtained from the specification, the information tends to become incorrect during maintenance. For example, do not make a point of listing all parameter names, modes, or subtypes when describing a procedure. This information is already available from the procedure specification. Similarly, do not list all subprograms of a package in the header unless this is necessary to make some important statement about the subprograms.

Do not include information in the header that the user of the program unit does not need. In particular, do not include information about how a program unit performs its function or why a particular algorithm was used. This information should be hidden in the body of the program unit to preserve the abstraction defined by the unit. If the user knows such details and makes decisions based on that information, the code may suffer when that information is later changed.

When describing the purpose of the unit, avoid referring to other parts of the enclosing software system. It is better to say "this unit does . . ." than to say "this unit is called by Xyz to do . . . ." The unit should be written in such a way that it does not know or care which unit is calling it. This makes the unit much more general purpose and reusable. In addition, information about other units is likely to become obsolete and incorrect during maintenance.

Include information about the performance (time and space) characteristics of the unit. Much of this information is not present in the Ada specification, but it is required by the user. To integrate the unit into a system, the user needs to understand the resource usage (CPU, memory, etc.) of the unit. It is especially important to note that when a subprogram call causes activation of a task hidden in a package body, the task may continue to consume resources after the subroutine ends.

notes

Some projects have deferred most of the commentary to the end rather than at the beginning of the program unit. Their rationale is that program units are written once and read many times and that long header comments make the start of the specification difficult to find.

exceptions

Where a group of program units are closely related or simple to understand, it is acceptable to use a single header for the entire group of program units. For example, it makes sense to use a single header to describe the behavior of Max and Min functions; Sin, Cos, and Tan functions; or a group of functions to query related attributes of an object encapsulated in a package. This is especially true when each function in the set is capable of raising the same exceptions.