Oracle PL/SQL Best Practices

Name

EXC-13: Document all package exceptions by module in package specifications.

Synopsis

Different programs may well raise different exceptions. You need to communicate this information clearly to users of your code so they know what to expect and what to code for. PL/SQL doesn’t offer a structured way to do this as part of the language ( Java, for example, does precisely that). So you need to come up with a standard convention for including such documentation in your code.

Example

The following package specification offers one simple example of how you might document the exceptions individual programs might raise:

CREATE OR REPLACE PACKAGE overdue
IS
   PROCEDURE analyze_status (...);
      /* analyze_status can raise:
            overdue.excessive_lateness
            overdue.fetch_out_of_sequence
      */

   FUNCTION count_by_borrower (...)
      RETURN INTEGER;
      /* count_by_borrower can raise:
            NO_DATA_FOUND
            borrower.does_not_exist
      */

Benefits

Programmers have a better sense of what to expect—and what kind of exception handlers to write—when using your code.

Challenges

It can be hard to take the necessary time to do this. Define it as part of your standard documentation for packages; then use code walkthroughs to identify omissions.