O'Reilly logo

Oracle PL/SQL Best Practices by Steven Feuerstein

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required