Ada 95 Quality and Style Guide Chapter 3

Chapter 3: Readability - TOC - 3.3 COMMENTS

3.3.4 Program Unit Body Headers


  • Place information required by the maintainer of the program unit in the body of the header
  • Explain how and why the unit performs its function, not what the unit does.
  • Do not repeat information (except unit name) in the header that is readily apparent from reading the code.
  • Do not repeat information (except unit name) in the body header that is available in the specification header.

  • instantiation

    - Put the name of the program unit in the header.
    - Record portability issues in the header.
    - Summarize complex algorithms in the header.
    - Record reasons for significant or controversial implementation decisions.
    - Record discarded implementation alternatives, along with the reason for discarding them.
    - Record anticipated changes in the header, especially if some work has already been done to the code to make the changes easy to accomplish.


    -- Autolayout
    -- Implementation Notes:
    --   - This package uses a heuristic algorithm to minimize the number
    --     of arc crossings.  It does not always achieve the true minimum
    --     number which could theoretically be reached.  However it does a
    --     nearly perfect job in relatively little time.  For details about
    --     the algorithm, see ...
    -- Portability Issues:
    --   - The native math package Math_Lib is used for computations of
    --     coordinate positions.
    --   - 32-bit integers are required.
    --   - No operating system specific routines are called.
    -- Anticipated Changes:
    --   - Coordinate_Type below could be changed from integer to float
    --     with little effort.  Care has been taken to not depend on the
    --     specific characteristics of integer arithmetic.
    package body Autolayout is
       -- Define
       -- Implementation Notes:
       --   - This routine stores a node in the general purpose Graph data
       --     structure, not the Fast_Graph structure because ...
       procedure Define
             (New_Node : in     Node) is
       end Define;
       -- Layout
       -- Implementation Notes:
       --   - This routine copies the Graph data structure (optimized for
       --     fast random access) into the Fast_Graph data structure
       --     (optimized for fast sequential iteration), then performs the
       --     layout, and copies the data back to the Graph structure.  This
       --     technique was introduced as an optimization when the algorithm
       --     was found to be too slow, and it produced an order of
       --     magnitude improvement.
       procedure Layout is
       end Layout;
       -- Position_Of
       function Position_Of (Current : in     Node)
             return Position is
       end Position_Of;
    end Autolayout;


    The purpose of a header comment on the body of a program unit is to help the maintainer of the program unit to understand the implementation of the unit, including tradeoffs among different techniques. Be sure to document all decisions made during implementation to prevent the maintainer from making the same mistakes you made. One of the most valuable comments to a maintainer is a clear description of why a change being considered will not work.

    The header is also a good place to record portability concerns. The maintainer may have to port the software to a different environment and will benefit from a list of nonportable features. Furthermore, the act of collecting and recording portability issues focuses attention on these issues and may result in more portable code from the start.

    Summarize complex algorithms in the header if the code is difficult to read or understand without such a summary, but do not merely paraphrase the code. Such duplication is unnecessary and hard to maintain. Similarly, do not repeat the information from the header of the program unit specification.


    It is often the case that a program unit is self-explanatory so that it does not require a body header to explain how it is implemented or why. In such a case, omit the header entirely, as in the case with Position_Of above. Be sure, however, that the header you omit truly contains no information. For example, consider the difference between the two header sections:

    -- Implementation Notes:  None.


    -- NonPortable Features:  None.

    The first is a message from the author to the maintainer saying "I can't think of anything else to tell you," while the second may mean "I guarantee that this unit is entirely portable."

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