Plsql DB Coding Standards

8/6/2019 Plsql DB Coding Standards

1/16

DB Coding Standards Version 2.0


2/16

TABLE OF CONTENTS

1 INTRODUCTION .................................................................................................................................... 11. NAMING CONVENTIONS ..................................................................................................................... 1

1.1 General guidelines on Naming Conventions ............. ............. .............. ............. ............. ............. ........ 11.2 Packages ........................................................................................................................................... 1

1.2.1 Package File Naming ................................................................................................................. 11.2.2 Package specification/body Naming ........................................................................................... 1

1.3 Function/Procedure ........................................................................................................................... 21.3.1 Function/Procedure File Naming ................................................................................................ 21.3.2 Function/Procedure Naming....................................................................................................... 2

1.4 Trigger .............................................................................................................................................. 21.4.1 Trigger File Naming .................................................................................................................. 21.4.2 Trigger Naming ......................................................................................................................... 3

1.5 Other User Objects ............................................................................................................................ 31.6 Variables........................................................................................................................................... 3

1.6.1 Variable Naming based on scope of the variable ............ .............. ............. ............. ............. ........ 31.6.2 Variable Naming based on type of argument .............................................................................. 41.6.3 Variable Naming based on Data type of the variable ............. ............. ............. .............. ............. . 4

2. PL/SQL PROGRAMMING GUIDELINES ............. ............. ............. ............. ............. ............. .............. ... 52.1 Cursor Handling ............ .............. ............. ............. ............. ............. .............. ............. ............. .......... 52.2 Error Handling .................................................................................................................................. 52.3 Exception Handling Strategy ............................................................................................................. 52.4 Variables and Data types ................................................................................................................... 62.5

Comparisons ..................................................................................................................................... 6

2.6 SQL Statements ................................................................................................................................ 62.7 Traceability and Readability .............................................................................................................. 72.8 General Programming Guidelines ...................................................................................................... 72.9 Coding Guidelines............................................................................................................................. 8

2.9.1 Modification Log ............ ............. .............. ............. ............. ............. ............. .............. ............. . 82.9.2 Case of the letters in code .......................................................................................................... 82.9.3 Spacing ..................................................................................................................................... 92.9.4 Indenting ................................................................................................................................... 92.9.5 Placement of comment blocks in code ...................................................................................... 102.9.6 Restrictions ............................................................................................................................. 10

3. DOCUMENTATION ............................................................................................................................. 10APPENDIX A ................................................................................................................................................ 12

Typical Code layout.................................................................................................................................... 12APPENDIX B ................................................................................................................................................ 13

Procedure/Function..................................................................................................................................... 13


3/16


4/16

Some examples are given below.

Name Prefix Example

load_comment_text_line(body) Pk pk _load_comment_text_line

load_comment_text_line(spec) Pk pk _load_comment_text_line

1.3 Function/Procedure1.3.1 Function/Procedure File Naming

Procedure and function file naming _.

Optional/Mandatory Description

Prefix M fn for functionspr for procedures

Name M Descriptive name of the procedure/function

File extension M sql for files containing procedure/function


Name Function/

Procedure

Prefix File extension Example

Date_difference Function fn sql fn_date_difference.sql

add_date Procedure pr sql pr_add_date.sql

1.3.2 Function/Procedure NamingThe following generic standards should be followed:

Consist of two parts: _


Prefix M fn for functions

pr for procedures

Name M Descriptive name of the procedure/function


Name Function/

Procedure

Prefix Example

date_difference Function fn fn_date_difference

Main Procedure pr pr_main

1.4 Trigger1.4.1 Trigger File Naming

Trigger file naming _.


Prefix M trg for triggers

Name M Descriptive name of the trigger as explained in the

trigger naming section 2.3.2

File extension M trg for files containing trigger



5/16

Name Trigger Prefix File extension Example

cm_bf_ins_row_check_integrity Trigger trg trg trg_cm_bf_ins_row_chec

k_integrity.trg

1.4.2 Trigger NamingThe following generic standards should be followed:

Consist of two parts: __[DEF_][_descriptive_text]


Prefix M trg for triggers

XXX M Table short name

DEF O Optional 3 character string DEF should be added

for default triggers (Auditing triggers)

I M Instance of trigger firing with valid values as

af for After

bf for BeforeR M Reason of trigger with valid values as

upd for Update

del for Delete

ins for Insert

T M Type of trigger with valid values as

row

stmt for Statement

O Optional - Descriptive name of the trigger


Name Trigger Prefix Example

Trigger on check_model table before insert to check data

integrity

Trigger trg trg_cm_bf_ins_row_check_integrity

1.5 Other User ObjectsOther User Objects are to be named as follows:

XXX_where,

XXX = 3 letter object typeVIU for Views

SEQ for Sequences

TRG for Triggers

ROL for Roles

1.6 Variables1.6.1 Variable Naming based on scope of the variable

Consist of three parts: _

The first letter always refers to the scope of the variable and all other letters before the _

(underscore) refer to the variables data type.

Optional/

Mandatory

Description

Scope M The scope of the variable: g - Scope is global; l - Scope is local

Type M Data Type of the variable Name M Descriptive name of the variable


6/16


Scope of the variable Prefix Description Example

Global g... Scope of this variable is full package or

procedure/functiongi_empno

Local l... Declared in a block and exists as longas the block is being processed. Blocks

outside to the above said block cannotaccess this variable.

lb_result

1.6.2 Variable Naming based on type of argumentConsist of three parts: __

Optional/

Mandatory

Description

Type of argument M Specifies the type of argument

in - Input parameter

out - Output parameterio - Input/Output parameter

Type M Data Type of the variable

Name M Descriptive name of the variable


Input/Output mode Type of argument Example

Input in_.. in_b_variable2

Output out_ out_l_variable3

in/out io_ io_i_variable4

1.6.3 Variable Naming based on Data type of the variableConsist of three parts : []_[]_

Data type Remaining letters of the Prefix Example

Boolean ..b_ lb_variable2

Character ..ch_ lch_variable3

Date ..d_ ld_variable4

Decimal ..dec_ ldec_variable6

Integer ..i_ li_variable8

Number ..n_ ln_variable9

Varchar ..v_ gv_variable10

Long ..l_ gl_variable11

Raw ..rw_ grw_variable12

Long raw ..lr_ glr_variable13

TYPE of some column oftable ..t_ gt_variable14

ROWTYPE oftable ..r_ gr_variable15

User defined exceptions ..e_ ge_variable16

PL/SQLtable ..tbl_ gtbl_variable17

There are some exception to the above said. Those are given in the following table.

In the following cases the name will consist of three parts: __

Data type Suffix Example

Cursor _cur g_variable18_cur

User defined record _rec g_variable19_rec

Constant _const g_variable20_const


7/16

For array types, the variable naming conventions mentioned above should be followed, additionally, _arr

should be added as a suffix to the variable name.

For example

Data type Example

Boolean Array lb_variable2_arr

Character Array lch_variable3_arr

Date Array ld_variable4_arrDecimal Array ldec_variable6_arr

Integer Array li_variable8_arr

2. PL/SQL PROGRAMMING GUIDELINES2.1 Cursor Handling

y Use parameterized cursors, if required.eg: CURSOR iosc_customers_cur (

in_customer_number iosc_customers.customer_number%TYPE,in_company_number iosc_customers.comapny_number%TYPE)

ISSELECT customer_id

FROM iosc_customers

WHERE customer_number = in_customer_number

AND company_number = in_company_number;

y Cursor records should be passed to the called program from the calling program. It cannot beaccessed globally in all subprograms within the pl/sql procedure.

y Avoid direct SQL statements in case of Zero query hits, when it is not functionally important tohandle NO_DATA_FOUND condition, since Zero query hits raises the NO_DATA_FOUND

exception. To handle this, a cursor should be defined and the no record found condition should be

properly processed.

y When no data is found, check that the closing of the cursor is handled properly, in case the cursoris handled by using OPEN, FETCH & CLOSE cursor.

y When records in a cursor are to be processed in a loop, try to use for cursor loop, as it handlesthe OPEN, FETCH & CLOSE of the cursor implicitly.

y While using Embedded PL/SQLs, group OPEN CURSOR statements for cursors that can beopened simultaneously in a BEGIN-END block. Group CLOSE CURSOR statements for cursors

that can be opened simultaneously in a BEGIN-END block.

2.2 Error Handlingy Every PL/SQL block should have an EXCEPTION block. All functionally related exceptions,

must be handled before the WHEN OTHERS THEN exception handler.

y Do not use DBMS_OUTPUT for displaying errors. Use the logging framework, which will beprovided.

y If you have cursors in your program, check for open cursors in the EXCEPTION block. Thishelps to closes any cursor that might have been left open when an exception occurs.

y For SELECT statement write handler for NO_DATA_FOUND, where in case of UPDATEstatement write SQL%NOTFOUND immediately after the statement. UPDATE statement, if does

not update any rows in table, does not raise NO_DATA_FOUND

2.3 Exception Handling StrategyThe Stored Procedures might be called from the Java code. The Java code will not be able to make the

SQL exceptions understandable for the user.

For eg: The Java code can call the stored procedure for searching Accommodation services availablein the system. In the stored procedure, if no services are available, the result of the query will be No


8/16

Data Found exception. Sending this exception to the Java code handle, might cause the business

logic to be layered in both DB Layer and Business Layer. So, this should be avoided.

This can be handled by declaring User Defined Exceptions in PLSQL. The error code used in bothJava layer and Database should be the same. The exception handling in the Java layer is mentioned in

the DLD guideline document.

The Java layer should refer the error code list maintained by it, for the message to be displayed to the

user.

2.4 Variables and Data typesy Variables, which are based on database, must be defined as %TYPE.

Example:

Table name inv_equipmentTable column name equipment_id

Variable name ln_equipment_id

ln_equipment_id inv_equipment.equipment_id%TYPE;

y Always qualify the variable with source table name, whenever the same column source appears inmore than one table.

y Limit the scope of variables to the area that they are needed.y Variables needed within a single script are to be declared as local variables.y Variables needed across an entire application are to be declared as global variables.y Initialise the variables during definition itself as far as possible.

Example:

ln_cut_off number := 12;

y If more than one variable is fetched in a cursor, use a %ROWTYPE variable instead of separatevariables.

y For variables used to store SQL statements and some intermediate results and that are not part ofthe table definition, make sure that the size of the variable is sufficiently large to hold the value.

y Do not initialise variables inside a loop unless dictated by the business logic.y Boolean should be initialised before the start of a loop.y The data types like RAW, LONG RAW can be used in the same way as the other scalar data

types, except that it should be kept in mind that they operate on binary data.

y LOB data types like BFILE, BLOB, CLOB cannot be manipulated directly. Use the DBMS_LOBpackage to manipulate LOB data types. Also keep in mind that LOBs are operated by means ofLOB locators, and locators cannot be used across sessions.

2.5 Comparisonsy Data types on either side of comparisons should match.y When comparing two variables for equality/inequality, if the variables can take NULL values, use

NVL () for comparison.

y NVL comparisons should be of the proper type. While using NVL (), use a date constant for adate comparison, a number constant for a number comparison and so on.

y All Date fields should have four-digit years or four digit comparisons.y Conversions should not be implied. A format mask must be used when TO_CHAR (), TO_DATE

conversion functions are used.

y For comparisons with constant values make sure that the constants are defined as PL/SQLconstant variables and are not hard-coded in IF statements. This helps in easier modification of

the constant value and also prevents the user from changing the constant value accidentally in the

course of the program.

2.6 SQL Statementsy In INSERT statements, do not assume the order of the fields in the table. The order of fields must

be mentioned explicitly, in the INSERT statement.


9/16

y Date fields should always be compared using a format mask. Use TRUNC in date comparisons toeliminate the time part of the date.

y Use meaningful aliases when writing queries to improve readability. Do not use aliases like A, B,C, etc,. Make sure to use aliases that have been defined in the FROM clause, in the SELECT

clause of the SQL statement.

Wrong way Right waySELECT A.emp_name , A.emp_id , B.job

FROM employee A , job B

WHERE A.emp_id = B.emp_id;

SELECT EMP.emp_name , EMP.emp_id ,JOB.job

FROM employee EMP , job JOB

WHERE EMP.emp_id = JOB.emp_id;

y Do not use count (*) in any SQL statement. Use count (column_name or primary key column)and/or restrict the SQL by a where clause as much as possible.

y Use EXISTS / NOT EXISTS in the place of IN, NOT IN.y Do not forget to use Outer Joins in SQL statements when columns with NULL values figure in the

join.

2.7 Traceability and Readabilityy Maintain a list of procedures/functions/packages that make use of a procedure in the procedures

header. This will help in impact analysis when the procedure needs to be modified and will also

help reduce defects during run time.

y Maintain another list of procedures/functions/packages, which are made use in this procedure.y When defining package variables or global variables, give sufficient comments explaining all the

variables.

y In the Comment header, mention the global variables being used by the PL/SQL program.y Maintain a mod-log for the procedures in the header.y Give sufficient comments for all the modifications.y Comments could be like

/* Added by Prathap on 21/10/2009. This piece of code writes to a log file */

2.8 General Programming Guidelinesy Do not use DBMS_OUTPUT for displaying error/debugging messages. Use appropriate logging

levels for all the log entries.

y Never commit in your pl-sql block. Commit and Rollback should be handled in the applicationcode only.

y Hard coding of values should be prevented. Use constants.y The program must be modular in structure.y Ideally a program should have only one RETURN statement. If possible try to avoid using

multiple return statements.

y Avoid the use of global variables in the program as far as possible. Pass parameters betweensubprograms.

y For common validations, do not hard code, use standard PL/SQL procedures. If no such routineexists already write a standard routine and add it to the library so that it is reusable. Place related

functions/procedures in a package and keep the package as small as possible.

y Never code more than one statement in a line.y Try to avoid Dynamic SQL as far as possible, i.e. avoid forming the query as a string based on

the data input.

y In Declaration section the following order should be maintained, global variables followed bylocal variables followed by cursor, function declaration.

y Code sharing- If a piece of code is needed in more than one place, a function or procedure for thesame is recommended.

y While using IF ELSE statements, place the condition that would be met most number of timesduring runtime as the first condition. This avoids executing conditions, which would not be met

during most of the times.

y Avoid accidental full table scans (!=, IS NULL, NOT IN, LIKE with leading wildcard, functionson indexed columns). Need to create functional indexes if functions are used on indexed columns.


10/16

y If you have a highly skewed distribution of values in an indexed column, convert a not equalsexpression into a pair of greater than and less than expressions. If the column is not indexed ,

always use a not equals expression instead.

y Use PL/SQL instead of using multiple SQL calls onto the DB.y Dont commit the transaction at each and every record if you can commit the whole transaction at

a time. A COMMIT takes the same time if you are committing one record or one million records.

The opposite is true for ROLLBACK.y Do not build applications that contain SQL statements that are identical except for their hard-

coded values for their where clauses. Use bind variables as this prevents re-parsing. This is veryimportant for scalability. No bind variables = no scalability. It is that simple.

y Do not code iterative single insert, update, or delete statements on a table within a PL/SQL loopwhen they can be done in bulk.

y All tables in the from clause must have a join condition in where clause. Should have minimumn-1 joins.

y Remove unnecessary table accessy Use like operator with a leading character as index will not be used. Use LIKE 'ABC%' and not

'%ABC' or '%ABC%

y Do not use sub queries, as they will adversely impact system performance, consume significantamounts of CPU resources, potentially cause CPU bottlenecks. Alternatively use inline views

which perform orders of magnitude faster.y Reduce the number of table lookups in the SQL statement particularly if your statement includes

sub query select or multicolumn update.

y Use composite indexes in place of separate single column indexes. Reduces bad index selection.y When doing a join of three or more tables, try to structure the query to do the greatest elimination

on the first join.

y Incorporating all of the restrictive where clause conditions on one table can often do this.y Dont use WHEN OTHERS exception. If used, there should be a RAISE associated with ity Dont use COUNT(*) and then if exists get the value from the table.y Get the value with an exception handler.y Do not use commits/rollbacks in PL/SQL procedures. Let application decide what needs to be

done. This helps in code-reuse as another program can use this code as part of its transaction.

Exception: queue related logic/multi threads.

y Use one PL/SQL package to store all global variables. This will help in changing code at oneplace instead of changing at many places. Dont use CHAR data types in this package.

2.9 Coding Guidelines2.9.1 Modification LogChange Modlog Structure

/******* Date Ver No: XX Begin modification ******************/

/******* Date Ver No: XX End modification ******************/

This is applicable if we have multiple people working on the same code.

2.9.2 Case of the letters in codeContext Case Example

Package/Trigger/Function/Procedure/Variable/ Table name

Lower pk _load_comment_text_line, ld_join_date

Keywords Upper IN, OUT, IN OUT, BEGIN, END, COMMIT,

EXCEPTION, WHEN OTHERS, TYPE, IF, ELSE,END IF, THEN, UPDATE, INSERT, SET,

DELETE, CREATE, REPLACE, PROCEDURE.

Built-in functions Upper SUBSTR, COUNT, TO_CHAR

Predefined data types Upper NUMBER (7,2), BOOLEAN, DATE


11/16

2.9.3 SpacingItem Space

before

Space

after

Example

Operators (+, -, *, /) One One a := b + c

Assignment verb (: =) One One x := y + z

Function arguments One None f_function( arg_1, arg_2, arg_3 )

Note: Space should be afterthe comma

Opening ( in functions None One f_function( arg_1, arg_2, arg_3 )

Closing ) in functions One None f_function( arg_1, arg_2, arg_3 )

2.9.4 IndentingItem Indenting Example

IF .. THEN

..

ELSE..

END IF;

Indentation of executable

statement is same as condition

There should be a single space between IF and condition and a

single space between conditionand THEN.

IF X > Y THEN

X :=Z;

END IF;

EXCEPTION

WHEN ....

WHEN OTHERS should start

from 4th character (i.e. E) ofEXCEPTION

EXCEPTION

WHEN OTHERS

FOR LOOP

END LOOP;

There should be a single space

between FOR and the loopvariable and a single space

between higher bound and

LOOP.


statement is same as loop

variable

FOR i IN 1..3 LOOP

DBMS_OUTPUT.PUT_LINE (i);END LOOP;

WHILE LOOPEND LOOP;

There should be a single space between WHILE and thecondition and a single space

between condition and LOOP.


statement is same as condition

WHILE i < 3 LOOP

DBMS_OUTPUT.PUT_LINE(i);

END LOOP;

LOOP

...

EXIT WHEN condition;

END LOOP;


statement is 3 spaces (it should

start below the P of LOOP).

There should be a single space

between WHEN and condition.

LOOP

DBMS_OUTPUT.PUT_LINE (i);

EXIT WHEN i >= 3;

END LOOP;

DECLARE

...

BEGIN...

...EXCEPTION

...

END

The declaration of variables

should have an indentation of 3

spaces (i.e. it should start belowL of DECLARE).

The statements in the BEGINblock should

have an indentation of 3 spaces

(i.e. it should start below I of

BEGIN).

DECLARE

count NUMBER := 3;

BEGINIF count > 3 THEN

DBMS_OUTPUT.PUT_LINE( > 3 );

ELSE

DBMS_OUTPUT.PUT_LINE

(


12/16

Item Indenting Example

UPDATE statements All the other keywords in the

UPDATE statement should be

right aligned to the UPDATE

keyword.

All the table fields specified in

the SET statement should be leftaligned.

UPDATE equipments

SET equipment_name = PC

WHERE equipment_id = 100;

INSERT statements All the other keywords in theINSERT statement should be

right aligned to the INSERT

keyword.

INSERT INTO equipments(equipment_id,

equipment_name)

VALUES

(101,MODEM);

2.9.5 Placement of comment blocks in codeBlock Placement Example

Header for functions/procedure Should be in the beginning of the code

in a box

See the sample code

layout in Appendix A

Comment line specifying start ofdeclaration

Should be placed immediately after theheader block

See the sample code


Comments forthe variables used

in scripts

Should be placed immediately after the

comment line specifying start ofdeclaration

See the sample code


Declaration of local variables See the sample code


Comment line specifying the end

of declaration

Should be placed immediately after the

declaration of local instances of classes

See the sample code


Comments Comments inside the code should be in a

block which explains a logic block and it

should be placed before the logic block

See the sample code


Comment line specifying the endof code

Should be placed at the end of code See the sample code


2.9.6 RestrictionsArea Should not Example

Comments Should not mix with the code.

HardCoding Should not hard code values. ArPmtSchKeys.Record_Type := 'INV';

Example - should not do hard coding

Wrong way Right wayArPmtSchKeys.Record_Type := 'INV'; ArPmtSchKeys.Record_Type := inv_type_variable;

Declare that variable in the beginning and assign this

value.

3. DOCUMENTATIONProviding good documentation is essential for any significant application. This includes both internal

documentation for developers and external documentation for end users.

Area Description

Package comments Each package should have a header describing the date, modification log.There should be a brief description for the purpose of the package. A


13/16

typical package header will be as given in Appendix A.

Script comments Documentation should have thorough commenting in all procedures and

function scripts. Comments should be written for all those operations in the

body of the script/function that are significant in the point of algorithm.

Function/Procedure

comments

Each function should have a header describing the date, modification log.

There should be a brief description for the purpose of the function and all

the parameters of function declaration. A typical function header will be asgiven in Appendix B.


14/16

APPENDIX A

TYPICAL CODE LAYOUT

A TYPICAL CODE LAYOUT will look like as given below:

/************************************************************************ TYPE : Package ** NAME : pk_iosc_utility ** INPUT Parameters : None ** OUTPUT Parameters : None ** PURPOSE : To club all the procedures which are used to get** foreign key fields of IOSC tables into a ** package, so that the procedures are available to** other packages. ** Global variables : None ** Procs./Fns. Used : None ** Used in Procs./Fns.: None ** ** Author Date Ver Description *

* ------ ---------- --- ---------------------------------------------** Shashi 18/11/1998 1.00 Created ** ************************************************************************/

CREATE OR REPLACE PACKAGE iosc_utility IS

/************************************************************************ TYPE : Procedure ** NAME : pr_get_iosc_address_id ** INPUT Parameters : None ** OUTPUT Parameters : None ** PURPOSE : gets the address_id from the table *

* iosc_addresses for a given address_number. ** DynaBuilds an iosc_addresses record if it ** does not exist ** Global variables : None ** Procs./Fns. Used : None ** Used in Procs./Fns.: None ** ** Author Date Ver Description ** ------ ---------- --- ---------------------------------------------** Shashi 18/11/1998 1.00 Created ** ************************************************************************/

PROCEDURE pk_get_iosc_address_id(

in_address_nbr IN iosc_addresses.address_number%TYPE,out_address_id OUT iosc_addresses.address_id%TYPE)

ISBEGIN

...

...END;

END pk_iosc_utility;


15/16

APPENDIX B

PROCEDURE/FUNCTION

/************************************************************************ TYPE : Procedure ** NAME : pr_get_employee_nbr ** INPUT Parameters : in_employee_name ** OUTPUT Parameters : out_employee_nbr ** PURPOSE : To create a new employee number if the employee ** name doesn't exist in employee table, otherwise ** return the existing employee number ** Global variables : None ** Procs./Fns. Used : None ** Used in Procs./Fns.: None ** ** Author Date Ver Description *

* ------ ---------- --- ---------------------------------------------** Shashi 18/11/1998 1.00 Created ** ************************************************************************/

PROCEDURE pr_get_employee_nbr(in_employee_name IN employee.name%TYPE,out_employee_nbr OUT employee.number%TYPE )

IS

lt_emp_nbr employee.number%TYPE;

CURSOR find_employee_id(in_emp_name employee.name%TYPE

) ISSELECT numberFROM employeeWHERE name = in_emp_name;

BEGIN

OPEN find_employee_id(in_employee_name);FETCH find_employee_id INTO lt_emp_nbr;

IF find_employee_id%NOTFOUND THENSELECT employee_seq.NEXTVAL

INTO lt_emp_nbrFROM dual;

INSERT INTO employee(number ,name)

VALUES(lt_emp_nbr ,in_employee_name);

END IF;

out_employee_nbr := lt_emp_nbr;


16/16

EXCEPTIONWHEN OTHERS THEN

error_pkg.process_sql_err ('pr_get_employee_nbr, sqlerrm);RAISE;

END pr_get_employee_nbr;

Plsql DB Coding Standards

Documents

Transcript of Plsql DB Coding Standards