PL/SQL Comments Best Practices Standards
Oracle Tips by Jonathan Ingram
PL/SQL Comments Best Practices
As much as some developers dislike the task, commenting code is essential if
the code is going to be maintained. There are a number of steps that can be
taken to make comments less necessary:
? Use meaningful
identifiers for variables, constants, and parameters. If you use abbreviations
to compose identifiers, use the abbreviations consistently (e.g., don't use both
ADDR and ADRS to signify ADDRESS).
? Use the named parameter
style of executing procedures and functions. This is especially effective if
both the parameters and the variables passed to the stored PL/SQL object have
? Comments about
revisions belong in the prologue, not in the body of the module.
Commenting Changes And Problem Tracking
If you?re using a problem-tracking system on your project, it's better to
reference a particular report from that system and provide a brief summary of
the changes made to solve that problem. Don't attempt to include all the
information about the problem in the prologue; that's why you bought a problem
? Break complex equations
and formulas into several smaller statements.
? Reuse existing
functions and procedures to accomplish your tasks. Identify code that can be
There are a number of locations in PL/SQL code where comments should almost
always be used, including the following instances:
? Before each loop
? Before each
? Before each conditional
logic expression (IF <condition> THEN).
? Before any other
logically significant statements.
Do not comment each line of code! Only comment important parts of your code,
explaining why the code is written in a particular way. Explain business rules
if possible. Never use a comment to restate the actions of a piece of code.
PL/SQL supports the following two styles of commenting:
/* We need to determine which students are in academic trouble. */
-- We need to determine which students are in academic trouble.
PL/SQL does not support the nesting of C-style comments; you cannot comment
out a C-style comment using other C-style comments. For this reason, it is
strongly recommended that only the double-dash (--) style of commenting be used
except when commenting out blocks of code.
The exception to this rule is inside 3GL programs that use the Oracle
Precompilers. The Oracle Precompilers don't support single line comments. On
these occasions, use the commenting style most appropriate to the 3GL.
If a comment is required, place the comment on the line immediately preceding
the line of code. Do not append comments to the end of code; if a comment is
warranted by the complexity of the code and you have used meaningful
identifiers, the comment should be complicated enough that you need to explain
the situation using more than one or two words.
-- Determine which students might be in trouble academically. We want
-- to help them perform better in school.
IF (some condition) THEN
IF (some condition) THEN -- who's got bad grades?
All comments should use proper grammar, punctuation, and spelling. Comments
should be complete, coherent sentences. As a general rule, about one-third
of your final code should be comments. This figure often varies depending on the
size and complexity of the code, but is an excellent rule of thumb.
This is an excerpt from "High Performance Oracle Database
Automation", by Jonathan Ingram and Donald K. Burleson, Series Editor.