Ada 95 Quality and Style Guide Chapter 3

Chapter 3: Readability - TOC - 3.3 COMMENTS

3.3.3 Program Unit Specification Headers


  • Put a header on the specification of each program unit.
  • Place information required by the user of the program unit in the specification header.
  • Do not repeat information (except unit name) in the specification header that is present in the specification.
  • Explain what the unit does, not how or why it does it.
  • Describe the complete interface to the program unit, including any exceptions it can raise and any global effects it can have.
  • Do not include information about how the unit fits into the enclosing software system.
  • Describe the performance (time and space) characteristics of the unit.

  • instantiation

    - Put the name of the program unit in the header.
    - Briefly explain the purpose of the program unit.
    - For packages, describe the effects of the visible subprograms on each other and how they should be used together.
    - List all exceptions that can be raised by the unit.
    - List all global effects of the unit.
    - List preconditions and postconditions of the unit.
    - List hidden tasks activated by the unit.
    - Do not list the names of parameters of a subprogram.
    - Do not list the names of package subprograms just to list them.
    - Do not list the names of all other units used by the unit.
    - Do not list the names of all other units that use the unit.


         -- 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;


    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.


    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.


    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.

    < Previous Page Search Contents Index Next Page >
    1 2 3 4 5 6 7 8 9 10 11
    Appendix References Bibliography