[Chapter 3] 3.7 Documenting the Entire Package

3.7 Documenting the Entire Package

A package is often a complicated and long construct. It is composed of many different types of objects, any of which may be public (visible to programs and users outside of the package) or private (available only to other objects in the package). Package structure is described in more detail in Chapter 16, Packages.

You can use some very simple documentation guidelines to clarify the structure of the package.

As usual when discussing packages, one must consider the specification separately from the body. As a meta-module or grouping of modules, the specification should have a standard header. This header needn't be as complicated as that of a specific module, because you do not want to repeat in the package header any information which also belongs in specific modules. I suggest using the template header shown in the following example. In the "Major Modifications" section of the header, do not include every change made to every object in the package. Instead note significant changes to the package as a whole, such as an expansion of scope, a change in the way the package and global variables are managed, etc. Place this header after the package name and before the IS statement:

PACKAGE package_name
/*
|| Author:
||
|| Overview:
||
|| Major Modifications (when, who, what)
||
*/
IS
   ...
END package_name;

3.7.1 Document the Package Specification

The package specification is, in essence, a series of declaration statements. Some of those statements declare variables, while others declare modules. Follow the same recommendation in commenting a package as you do in commenting a module's declaration section: provide a comment for each declaration. In addition to the comments for a specific declaration, you may also find it useful to provide a banner before a group of related declarations to make that connection obvious to the reader.

Surround the banner with whitespace (blank lines for the start/end of a multiline comment block). While you can use many different formats for this banner, use the simplest possible design that gets the point across. Everything else is clutter.

The package specification below illustrates the header and declaration-level comment styles, as well as group banners:

PACKAGE rg_select
/*
|| Author: Steven Feuerstein, x3194
||
|| Overview: Manage a list of selected items correlated with a
||    block on the screen.
||
|| Major Modifications (when, who, what)
||    12/94 - SEF - Create package
||    3/95  - JRC - Enhance to support coordinated blocks
||
*/
IS
   /*----------------- Modules to Define the List -------------------*/

   /* Initialize the list/record group. */
   PROCEDURE init_list (item_name_in IN VARCHAR2);

   /* Delete the list */
   PROCEDURE delete_list;

   /*------------------ Modules to Manage Item Selections -----------*/

   /* Mark item as selected */
   PROCEDURE select_item (row_in IN INTEGER);

   /* De-select the item from the list */
   PROCEDURE deselect_item (row_in IN INTEGER);

END rg_select;

3.7.2 Document the Package Body

The body is even longer and more complex than the specification. The specification contains only declarations, and only the declarations of public or global objects. The body contains the declarations of all private variables, cursors, types, etc., as well as the implementation of all cursors and modules. My suggestion for commenting declarations in the package body is, again, to provide a single line (or more) for each declaration, separated by whitespace. This takes more space, but is very legible.

Once you get beyond the variables, use banners for any and all of the following:

The private modules of the package. These should come after the package variable declarations, but before the public module implementations. The banner alerts a reader to the fact that these modules were not in the specification.
The public modules of the package. The package specification describes only the interface to these modules. The body contains the full code for those modules. Use a banner to let the reader know that you are done with variables and private modules.
Groups of related modules, particularly those with the same, overloaded name. (Overloading occurs when you create multiple modules with the same name but different parameter lists.)

The banners for a package body are shown below:

PACKAGE BODY package_name
IS
   /*----------------------- Package Variables ----------------------*/
   ... declarations placed here

   /*----------------------- Private Modules ------------------------*/
   FUNCTION ...
   PROCEDURE ...

   /*----------------------- Public Modules -------------------------*/
   FUNCTION ...
   PROCEDURE ...

END package_name;

Whether in a package or an individual module, make sure that your comments add value to the code. Do not repeat what the code itself clearly states. When dealing with a structure as complicated as a package, however, you need comments which focus on communicating that structure. If your package has more than a handful of modules, and especially if it uses both private and public modules, you should make sure to use these banners to keep the reader fully informed about the context of the code they are reading in the package.


3.6 Using Comments Effectively		II. PL/SQL Language Elements