Oracle PL/SQL Best Practices

Name

STYL-03: Standardize module and program headers.

Synopsis

While you should generally keep comments to a minimum in your code (see [STYL-09: Comment tersely with value-added information.]), it’s extremely important to create and keep current a standard header for all programs. This header should contain, at a minimum, the following elements:

• Version, author, and copyright information : What is the version of the code? Who wrote the program, who owns the program, etc.

• Access information : Where is the program stored? On disk in a file? Within the database under a certain schema?

• Overview : What does this program do?

• Dependencies : What does this program need to have defined, or have access to, in order to run properly?

• Algorithms : Are any algorithms of special note used in the program? If so, specify them and/or supply a more detailed description of the theory of operation (if there is one).

• Scope : What application module(s) was the program written for (if it’s not a generic library-type of program)? Frequently, packages are backend components of a system with a complex frontend. For example, a set of packages might comprise the Payroll subsystem.

• Modification history : What modifications have been made to the program? Include a line entry for each change to the program, showing who, when, and what. Put the entries in date-descending order, so that the most recent change is at the top.

• Exceptions : What errors might be raised by the program?

You are best off defining this header ...