PL/SQL Comments

Summary: in this tutorial, you will learn how to use PL/SQL comments including single-line and multi-line comments that allow you to improve the readability of your code.

Introduction to PL/SQL Comments

PL/SQL comments allow you to describe the purpose of a line or a block of PL/SQL code.

When compiling the PL/SQL code, the Oracle precompiler ignores comments. However, you should always use comments to make your code more readable and to help you and other developers understand it better in the future.

PL/SQL has two comment styles: single-line and multi-line comments.

Single-line comments

A single-line comment starts with a double hyphen ( --) that can appear anywhere on a line and extend to the end of the line.

For example, the following single-line comment explains the meaning of the co_vat_rate constant:

-- valued added tax 10%
DECLARE co_vat_rate CONSTANT NUMBER := 0.1; 
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

Sometimes, while testing a program, you may use a single-line comment to disable a line of code. The following illustrates how to comment out a line of code:

-- UPDATE products SET list_price = 0 WHERE product_id = l_id;
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

If you want to comment just a portion of a line, you can also use the single-line comment. The following example shows how to comment out the WHERE clause of the UPDATE statement. All the code which follows the double-hyphen -- to the rest of the line will be treated as a comment:

UPDATE products SET list_price = 0; -- WHERE product_id = l_id;
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

Note that we add the semicolon (;) before the (--) to make the statement valid.

Multi-line comments

A multi-line comment starts with a slash-asterisk ( /* ) and ends with an asterisk slash ( */ ), and can span multiple lines:

/*
  This is a multi-line comment
  that can span multiple lines
*/
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

Note that it is possible to use a multi-line comment as a single-line comment:

/* A multi-line comment can be used as a single-line comment */
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

We often use a multi-line comment to describe the purpose of a block of code like the following example:

/*
    This code allow users to enter the customer id and 
    return the corresponding customer name and credit limit
*/
DECLARE
    l_customer_name customers.name%TYPE;
    l_credit_limit customers.credit_limit%TYPE;
BEGIN
   ...
END;
/
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

For the maintainability, it is not a good practice to mix comments as follows:

BEGIN
    -- single-line comment /* another comment */
    NULL;
    /* 
        multi-line comment 
        -- that has another single-line comment 
    */
END;
/
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

Instead, use the following:

BEGIN
    -- single-line comment, another comment
    NULL;
    /* 
        multi-line comment 
        that has another single-line comment 
    */
END;
/Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

PL/SQL comment usage notes

PL/SQL does not allow you to nest a multi-line comment within another multi-line comment. The following code block is not valid:

BEGIN
    /* 
        a multi-line comment 
        /*
            a nested multi-line comment
        */
    */ -- -> error
END;
/
Code language: PostgreSQL SQL dialect and PL/pgSQL (pgsql)

For a PL/SQL block that will be processed dynamically, you cannot use single-line comments. Because Oracle precompiler will ignore the end-of-line characters that cause the single-line comments to extend to the end of the block. In this case, you can use multi-line comments instead.

In this tutorial, you have learned about PL/SQL comments including single-line and multi-line comments that allow you to document the purpose of your code.