Commenting in PL/pgSQL is done through two methods. The first method is a single line comment. These comments begin with two dashes (--) to express the line is a comment. The second type of comment is called a block comment. It begins with a forward slash asterisk (/*) and ends with an asterisk and another forward slash (*/). It is capable of spanning over multiple lines. Unlike PostgreSQL comments, block comments cannot be nested, but single line comments can. For example:

Example 9-5. PL/pgSQL Comments

 
-- This is a single line comment
/* This block comment spans 
*  over multiple 
*  lines /* this nested comment is illegal*/
-- this nested comment is valid
*  because it is inside of a block comment*/
   

Like in any programming language, it is helpful if you write good comments. A comment can be considered good if it can express to the user why you programmed it the way it is. Comments that restate what you are doing are not anymore helpful to the user. For instance, the comments in this function are irrelevant to why it is doing things the way it is:

Example 9-6. Commenting with no Purpose

   CREATE FUNCTION mult_two(integer) RETURNS integer AS'
   DECLARE   
     -- declares an input1 variable 
     input1 ALIAS FOR $1;
   
     -- declares a variable
     answer integer;
   BEGIN
     -- assigns to the answer 
     -- the result of input1 times 2 
     answer = input1 * 2;
 
     -- returns the variable
     return answer;
   END;
   ' LANGUAGE 'plpgsql';
   

Instead, you should make comments like these:

Example 9-7. Commenting with a Purpose

   CREATE FUNCTION mult_two(integer) RETURNS integer AS'
   DECLARE   
     -- defines a name for the first input 
     input1 ALIAS FOR $1;
   
     -- a variable to hold the answer
     answer integer;
   BEGIN
     -- multiples the input number by 2
     -- and stores it in the answer 
     answer = input1 * 2;
 
     -- displays the answer
     return answer;
   END;
   ' LANGUAGE 'plpgsql';

Comments in this part will have a little of both styles because we are not only showing you why but also what we are doing in the code.