Section 3.6.  Comments

3.6. Comments Inline documentation, otherwise known as comments , is an important element of a good program. While this book offers many suggestions on how to make your program self-documenting through good naming practices and modularization, such techniques are seldom enough by themselves to communicate a thorough understanding of a complex program. PL/SQL offers two different styles for comments: single-line and multiline block comments. 3.6.1. Single-Line Comment Syntax The single-line comment is initiated with two hyphens (), which cannot be separated by a space or any other characters. All text after the double hyphen to the end of the physical line is considered commentary and is ignored by the compiler. If the double hyphen appears at the beginning of the line, the whole line is a comment. Remember: the double hyphen comments out the remainder of a physical line, not a logical PL/SQL statement. In the following IF statement, I use a single-line comment to clarify the logic of the Boolean expression: IF salary < min_salary (2003) -- Function returns min salary for year. THEN salary := salary + salary*.25; END IF; 3.6.2. Multiline Comment Syntax While single-line comments are useful for documenting brief bits of code or ignoring a line that you do not want executed at the moment, the multiline comment is superior for including longer blocks of commentary. Multiline comments start with a slash-asterisk (/*) and end with an asterisk-slash (*/). PL/SQL considers all characters found between these two sequences of symbols to be part of the comment, and they are ignored by the compiler. The following example of multiline comments shows a header section for a procedure. I use the vertical bars in the left margin so that, as the eye moves down the left edge of the program, it can easily pick out the chunks of comments: PROCEDURE calc_revenue (company_id IN NUMBER) IS /* | Program: calc_revenue | Author: Steven Feuerstein | Change history: | 9/23/94 - Start program | 06-JUN-1999 - Y2K okay */ BEGIN ... END; You can also use multiline comments to block out lines of code for testing purposes. In the following example, the additional clauses in the EXIT statement are ignored so that testing can concentrate on the a_delimiter function: EXIT WHEN a_delimiter (next_char) /* OR (was_a_delimiter AND NOT a_delimiter (next_char)) */ ;