Oracle PL/SQL Best Practices

Name

STYL-09: Comment tersely with value-added information.

Synopsis

The best way to explain what your code is doing is to let that code speak for itself. You can take advantage of many self-documentation techniques, including:

• Define variables and call programs (local modules, in particular; see [MOD-04: Use named notation to clarify, self-document, and simplify module calls.]) to give names to and hide complex expressions.

• Use the language construct that best reflects the code you are writing (declare CONSTANTS when values don’t change, choose the right kind of loop for your logic, etc.).

Whenever you find yourself adding a comment to your code, first consider whether it is possible to modify the code itself to express your comment. Good reasons to add comments include:

• Program headers (see [STYL-03: Standardize module and program headers.])

• Explanations of workarounds, patches, operating-system dependencies, and other “exceptional” circumstances

• Complex or opaque logic

Example

Let’s follow a trail of unnecessarily commented code to self-documenting code. I start with:

/* If the first field of the properties record is N... */
IF properties_flag.field1 = 'N' 

Yikes! My line of code was incomprehensible and my comment simply repeated the code using the English language, rather than PL/SQL. No added value, no real assistance, yet not at all uncommon. The least I can do is use the comment to “translate” from computer-talk to business requirement:

/* If the customer is not eligible for a ...