11.1 Comments

The double hyphen (--) is used to comment a single line. A slash followed by an asterisk (/*) begins a block comment. An asterisk followed by a slash (*/) ends a block comment.

The C-style comments (/*, */) can be used to block out a section of code. The following procedure illustrates both forms.

 -- Filename hello.sql CREATE OR REPLACE PROCEDURE hello IS     str CONSTANT VARCHAR2(15) := 'Hello World!';     len INTEGER; /* length of the constant */ BEGIN     --     -- Set len to length of character string.     --     len := LENGTH(str);     /*     * write the string length     */     dbms_output.put_line(str'-string length:'len); END hello; 

Place comments after the CREATE statement, not before. This only applies if you are using a text editor with a tool like SQL*Plus ”a tool such as JDeveloper will not permit you to place comments prior to a CREATE statement. The situation to avoid is the following:

 -- This procedure prints hello. CREATE OR REPLACE PROCEDURE hello IS     str CONSTANT VARCHAR2(10) := 'Hello World!';     . . . etc 

Comments that precede the CREATE statement are not included with the source code saved in the data dictionary. Comments after the CREATE clause are stored in the data dictionary.

Packages require extensive comments, mostly because they typically have many procedures and functions that provide a wealth of functionality. A package should have overview comments that describe the package. This overview should document any Oracle privileges required to use the package. It should also document the need for any database parameter settings.

Sometimes there is an ordered dependency among the subprograms in the package. For example, to use a package properly, you may have to call one subprogram first, prior to calling other procedures. You want to document this dependency.

An overview that includes examples that demonstrate how to use the package is very useful. These overview comments immediately follow the CREATE PACKAGE statement. Following the general comments are the procedure and function definitions, which have individual comments.

 PACKAGE students_pkg is -- --  general comments about how to use the package  --     --     --  comments on print_name  PROCEDURE print_name (v_student_id IN VARCHAR2);     --     --  comments on print_major  PROCEDURE print_major (v_student_id IN VARCHAR2); END students_pkg; 

The Oracle built-in packages are well documented with an overview section, frequently including examples, plus detailed comments on each procedure and function.

Packages you can use are available through the ALL_SOURCE view. This view contains the source you have written, as well as code in other schemas to which you have access. This includes the Oracle built-in packages. The interface and comments that describe the DBMS_OUTPUT package can be extracted from the ALL_SOURCE view with a SQL statement similar to that used to extract the HELLO source and comments.

 SQL> SELECT text FROM all_source   2  WHERE name='DBMS_OUTPUT'   3  AND type='PACKAGE';