Call now: 252-767-6166  
Oracle Training Oracle Support Development Oracle Apps

 
 Home
 E-mail Us
 Oracle Articles
New Oracle Articles


 Oracle Training
 Oracle Tips

 Oracle Forum
 Class Catalog


 Remote DBA
 Oracle Tuning
 Emergency 911
 RAC Support
 Apps Support
 Analysis
 Design
 Implementation
 Oracle Support


 SQL Tuning
 Security

 Oracle UNIX
 Oracle Linux
 Monitoring
 Remote s
upport
 Remote plans
 Remote
services
 Application Server

 Applications
 Oracle Forms
 Oracle Portal
 App Upgrades
 SQL Server
 Oracle Concepts
 Software Support

 Remote S
upport  
 Development  

 Implementation


 Consulting Staff
 Consulting Prices
 Help Wanted!

 


 Oracle Posters
 Oracle Books

 Oracle Scripts
 Ion
 Excel-DB  

Don Burleson Blog 


 

 

 


 

 

 
 

PL/SQL Comments Best Practices Standards

Oracle Tips by Jonathan Ingram
 

PL/SQL Comments Best Practices Standards

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 meaningful identifiers.

?  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 tracking system!


?  Break complex equations and formulas into several smaller statements.

?  Reuse existing functions and procedures to accomplish your tasks. Identify code that can be reused.

There are a number of locations in PL/SQL code where comments should almost always be used, including the following instances:

?  Before each loop structure.

?  Before each BEGIN?END sub-block.

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

Correct:

--
-- Determine which students might be in trouble academically. We want
-- to help them perform better in school.
--
IF (some condition) THEN

Incorrect:

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.
 

If you like Oracle tuning, you might enjoy my book "Oracle Tuning: The Definitive Reference", with 950 pages of tuning tips and scripts. 

You can buy it direct from the publisher for 30%-off and get instant access to the code depot of Oracle tuning scripts.


 

 

��  
 
 
Oracle Training at Sea
 
 
 
 
oracle dba poster
 

 
Follow us on Twitter 
 
Oracle performance tuning software 
 
Oracle Linux poster
 
 
 

 

Burleson is the American Team

Note: This Oracle documentation was created as a support and Oracle training reference for use by our DBA performance tuning consulting professionals.  Feel free to ask questions on our Oracle forum.

Verify experience! Anyone considering using the services of an Oracle support expert should independently investigate their credentials and experience, and not rely on advertisements and self-proclaimed expertise. All legitimate Oracle experts publish their Oracle qualifications.

Errata?  Oracle technology is changing and we strive to update our BC Oracle support information.  If you find an error or have a suggestion for improving our content, we would appreciate your feedback.  Just  e-mail:  

and include the URL for the page.


                    









Burleson Consulting

The Oracle of Database Support

Oracle Performance Tuning

Remote DBA Services


 

Copyright © 1996 -  2020

All rights reserved by Burleson

Oracle ® is the registered trademark of Oracle Corporation.