3.5 Formatting Packages

A package is a collection of related objects, including variables, TYPE statements (to define structures for records, tables, and cursors), exceptions, and modules. We have already covered structuring all the different objects which make up a package. Now, let's take a look at how to structure the package itself.

A package has both a specification and a body. The package specification contains the declarations or definitions of all those objects that are visible outside of the package -- the public objects. This means that the objects can be accessed by any account that has been granted EXECUTE authority on the package. The package body contains the implementation of all cursors and modules defined in the specification, and the additional declaration and implementation of all other package objects. If an object, such as a string variable, is declared in the body and not in the package, then any module in the package can reference that variable, but no program outside of the package can see it. That variable is invisible or private to the package.

The first point to make about the package structure is that all objects declared in the specification exist within the context of the package and so should be indented from the PACKAGE statement itself, as shown below:

PACKAGE rg_select
IS
   list_name VARCHAR2(60);

   PROCEDURE init_list
      (item_name_in IN VARCHAR2,
       fill_action_in IN VARCHAR2 := 'IMMEDIATE');
   PROCEDURE delete_list;
   PROCEDURE clear_list;

END rg_select;

The same is true for the package body. I suggest that you always include a label for the END statement in a package so that you can easily connect up that END with the end of the package as a whole. I place the IS keyword on a new line to set off the first declaration in the package from the name of the package. You could always use a blank line. Notice that I use blank lines in rg_select to segregate different modules which are related by function. I think that logical grouping is always preferable to an arbitrary grouping such as alphabetical order.

The other important element in formatting a package is the order in which objects are listed in the package. I generally list objects in the order of complexity of their structure, as follows:

• Scalar variables, such as a VARCHAR2 declaration

• Complex datatypes, such as records and tables

• Database-related declarations, such as cursors

• Named exceptions

• Modules (procedures and functions)

As with simple variable declarations, I sometimes have many different but related objects in my package. If so, I might group those types of objects together. But within that grouping, I still follow the above order.