O'Reilly logo

Oracle PL/SQL Best Practices by Steven Feuerstein

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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:

  • 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:

  • 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 ...

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required