Oracle PL/SQL Language Pocket Reference- P9

Previous: 3.4 Formatting PL/SQL Blocks Chapter 3Effective Coding Style Next: 3.6 Using Comments Effectively 3.5 Formatting Packages A package is a collection of related objects, includin

Trang 1

total_type IN VARCHAR2 ALL or NET

);

/*

|| For every employee hired more than five years ago,

|| give them a bonus and send them an e-mail notification

The first example uses the single-line comment syntax to include endline descriptions for each

parameter in the procedure specification The second example uses a multiline comment to explain the purpose of the FOR loop The third example uses the double-hyphen to comment out a whole line

of code The last example embeds a comment in the middle of a line of code using the block

comment syntax

These two types of comments offer the developer flexibility in how to provide inline documentation The rest of this section offers guidelines for writing effective comments in your PL/SQL programs

3.6.1 Comment As You Code

It is very difficult to make time to document your code after you have finished writing your program Psychologically, you want to (and often need to) move on to the next programming challenge after you get a program working

You may also have a harder time writing your comments once you have put some distance between your brain cells and those lines of code Why exactly did you write the loop that way? Where

precisely is the value of that global variable set? Unless you have total recall, post-development

documentation can be a real challenge

The last and perhaps most important reason to write your comments as you write your code is that the resulting code will have fewer bugs and (independent of the comments themselves) be easier to

Trang 2

understanding of what the program does or should do

The effort that you make to come up with the right comment will certainly improve your

comprehension, and may also result in code correction In this sense, good inline documentation can

be as beneficial as a review of your code by a peer In both cases, the explanation will reveal

important information about your program

3.6.2 Explain the Why Not the How of Your Program

What do you think of the comments in the following Oracle Forms trigger code?

If the total compensation is more than the maximum

IF :employee.total_comp > maximum_salary

THEN

Inform the user of the problem

MESSAGE ('Total compensation exceeds maximum Please

In addition, use comments to translate internal, computer-language terminology into something meaningful for the application Suppose you are using Oracle Forms GLOBAL variables to keep track of a list of names entered Does the following comment explain the purpose of the code or simply restate what the code is doing?

/* Set the number of elements to zero */

:GLOBAL.num_elements := 0;

Once again, the comment adds no value Does the next comment offer additional information?

/* Empty the list of names */

:GLOBAL.num_elements := 0;

Trang 3

This comment actually explains the purpose of the assignment of the global to zero By setting the number of elements to zero, I will have effectively emptied the list This comment has translated the

"computer lingo" into a description of the effect of the statement Of course, you would be even

better off hiding the fact that you use this particular global variable to empty a list and instead build a procedure as follows:

and the meaning would be perfectly clear

3.6.3 Make Comments Easy to Enter and Maintain

You shouldn't spend a lot of time formatting your comments You need to develop a style that is clean and easy to read, but also easy to maintain When you have to change a comment, you shouldn't have to reformat every line in the comment Lots of fancy formatting is a good indication that you have a high-maintenance documentation style The following block comment is a maintenance

Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.

Trang 4

===========================================================

| Parameter - Description

|

| company_id - The primary key to company

| start_date - Start date used for date range

| end_date - End date for date range

I put the comment markers on their own lines to increase the whitespace in my program and set off the comment That way I can avoid "heavy" horizontal lines full of delimiters, such as asterisks or dashes, and avoid having to match the longest line in the comment

3.6.4 Maintain Indentation

Inline commentary should reinforce the indentation and therefore the logical structure of the program For example, it is very easy to find the comments in the make_array procedures shown below I do not use any double-hyphens, so the slash-asterisk sequences stand out nicely In addition, all

comments start in the first column, so I can easily scan down the left-hand side of the program and pick out the documentation:

PROCEDURE make_array (num_rows_in IN INTEGER)

/* Create an array of specified numbers of rows */

IS

/* Handles to Oracle Forms structures */

col_id GROUPCOLUMN;

rg_id RECORDGROUP;

Trang 5

/* Create new record group and column */

rg_id := CREATE_GROUP ('array');

col_id := ADD_GROUP_COLUMN ('col');

/*

|| Use a loop to create the specified number of rows and

|| set the value in each cell

*/

FOR row_index IN 1 num_rows_in

LOOP

/* Create a row at the end of the group to accept data */

ADD_GROUP_ROW (return_value, END_OF_GROUP);

FOR col_index IN 1 num_columns_in

LOOP

/* Set the initial value in the cell */

SET_GROUP_NUMBER_CELL (col_id, row_index, 0);

LOOP

END LOOP;

Your eye follows the three-space indentation very smoothly into the loop and then you are forced to move all the way to the left to pick up the comment This format disrupts your reading of the code and therefore its readability The code loses some of its ability to communicate the logical flow "at a glance," because the physical sense of indentation as logical flow is marred by the comments Finally, you may end up writing full-line comments which are much longer than the code they appear next to, further distorting the code

Your comments should always be indented at the same level as the code which they describe

Assuming the comments come before the code itself, those lines of descriptive text will initiate the indentation at that logical level, which will also reinforce that structure The make_array procedure, properly indented, is shown below:

PROCEDURE make_array (num_rows_in IN INTEGER)

/* Create an array of specified numbers of rows */

IS

Trang 6

/* Handles to Oracle Forms structures */

col_id GROUPCOLUMN;

rg_id RECORDGROUP;

BEGIN

/* Create new record group and column */

rg_id := CREATE_GROUP ('array');

col_id := ADD_GROUP_COLUMN ('col');

ADD_GROUP_ROW (return_value, END_OF_GROUP);

LOOP

3.6.5 Comment Declaration Statements

I propose the following simple rule for documenting declaration statements:

Provide a comment for each and every declaration.

Does that sound excessive? Well, I must admit that I do not follow this guideline at all times, but I bet people who read my code wish I had The declaration of a variable which seems to me to be perfectly clear may be a source of abiding confusion for others Like many other people, I still have difficulty understanding that what is obvious to me is not necessarily obvious to someone else

Consider the declaration section in the next example The commenting style is inconsistent I use double-hyphens for a two-line comment; then I use the standard block format to provide information about three variables all at once I provide comments for some variables, but not for others It's hard

to make sense of the various declaration statements:

Trang 7

|| Variables used to keep track of string scan:

|| atomic_count - running count of atomics scanned

|| still_scanning - Boolean variable controls WHILE

Next: 3.7 Documenting the Entire Package

3.5 Formatting Packages Book Index 3.7 Documenting the Entire

Trang 8

Trang 9

Previous: 3.4 Formatting

PL/SQL Blocks

Chapter 3Effective Coding Style

Next: 3.6 Using Comments Effectively

3.5 Formatting Packages

A package is a collection of related objects, including variables, TYPE statements (to define

structures for records, tables, and cursors), exceptions, and modules We have already covered

structuring all the different objects which make up a package Now, let's take a look at how to

structure the package itself

A package has both a specification and a body The package specification contains the declarations or definitions of all those objects that are visible outside of the package the public objects This means that the objects can be accessed by any account that has been granted EXECUTE authority on the package The package body contains the implementation of all cursors and modules defined in the specification, and the additional declaration and implementation of all other package objects If an object, such as a string variable, is declared in the body and not in the package, then any module in the package can reference that variable, but no program outside of the package can see it That

variable is invisible or private to the package

The first point to make about the package structure is that all objects declared in the specification exist within the context of the package and so should be indented from the PACKAGE statement itself, as shown below:

The same is true for the package body I suggest that you always include a label for the END

statement in a package so that you can easily connect up that END with the end of the package as a

Trang 10

whole I place the IS keyword on a new line to set off the first declaration in the package from the name of the package You could always use a blank line Notice that I use blank lines in rg_select to segregate different modules which are related by function I think that logical grouping is always preferable to an arbitrary grouping such as alphabetical order

The other important element in formatting a package is the order in which objects are listed in the package I generally list objects in the order of complexity of their structure, as follows:

● Scalar variables, such as a VARCHAR2 declaration

● Complex datatypes, such as records and tables

● Database-related declarations, such as cursors

● Named exceptions

● Modules (procedures and functions)

As with simple variable declarations, I sometimes have many different but related objects in my package If so, I might group those types of objects together But within that grouping, I still follow the above order

PL/SQL Blocks

Oracle PL/SQL Programming, 2nd Edition

Next: 3.6 Using Comments Effectively

Trang 11

Control Structures

Chapter 3Effective Coding Style

Next: 3.5 Formatting Packages

15, Procedures and Functions, for more information about the block structure.)

Consider the following function:

FUNCTION

company_name (company_id_in IN company.company_id%

TYPE) RETURN

VARCHAR2 IS cname company.company_id%TYPE; BEGIN

SELECT name INTO cname FROM company

WHERE company_id = company_id_in;

RETURN cname;

EXCEPTION WHEN NO_DATA_FOUND THEN RETURN NULL; END;

You know that this program is a function because the first word in the program is FUNCTION Other than that, however, it is very difficult to follow the structure of this program Where is the declaration section? Where does the executable section begin and end?

Here is that same function after we apply some straightforward formatting rules to it:

FUNCTION company_name (company_id_in IN company.company_id

%TYPE)

Trang 12

RETURN VARCHAR2

IS

cname company.company_id%TYPE;

BEGIN

SELECT name INTO cname FROM company

WHERE company_id = company_id_in;

Now it is easy to see that the header of the function consists of:

FUNCTION company_name (company_id_in IN company.company_id

%TYPE)

RETURN VARCHAR2

The declaration section, which comes after the IS and before the BEGIN, clearly consists of a single declaration of the cname variable The executable section consists of all the statements after the BEGIN and before the EXCEPTION statement; these are indented in from the BEGIN Finally, the exception section shows a single specific exception handler and a WHEN OTHERS exception

Generally, indent the statements for a given section from the reserved words which initiate the section You can also include a blank line before each section, as I do above, for the executable section (before BEGIN) and the exception section (before EXCEPTION) I usually place the IS keyword on its own line to clearly differentiate between the header of a module and its declaration section

Control Structures

Next: 3.5 Formatting Packages

3.3 Formatting Control

Structures

The Oracle Library

Navigation

Trang 13

SQL Statements

Chapter 3 Effective Coding Style

Next: 3.4 Formatting PL/

SQL Blocks

3.3 Formatting Control Structures

The control structures in your program are the most direct representation of the logic needed to implement your

specifications The format of these control structures, therefore, will have a significant impact on the readability of your code

Indentation is the most important element of control structure layout Always keep statements of the same "logical level"

at the same indentation level Let's see what this means for the various control structures of PL/SQL

IF <expression>

ELSEIF <expression>

ELSE END IF;

In general, the IF statement is composed of clauses in which there is a Boolean expression or condition and a section of code executed when that condition evaluates to TRUE

So if you want to use indentation to reveal the logical structure of the simplest form of the IF statement (IF-END IF), I suggest one of these two styles:

New Line for THEN Same Line for THEN

else_executable_statements; END IF;

Trang 14

ELSEIF <expression2> THEN executable_statements2;

ELSEIF <expressionN> THEN executable_statementsN;

ELSE else_executable_statements; END IF;

Notice that in both versions the executable statements are indented three spaces from the column in which the IF and END IF reserved words are found The only difference between the two formats is the placement of the THEN reserved word I prefer the new line format, in which the THEN appears on a line by itself after the IF condition This format provides more whitespace than the other I could create the whitespace by using a blank, rather than indenting three spaces, but then the executable statements for the IF clause are made distinct from the condition and they are logically connected Let's examine some actual code to get a better sense of the differences

The following example shows proper IF statement indentation with THEN on the same line:

PL/SQL offers the following kinds of loops:

● Infinite or simple loop

● WHILE loop

● Indexed FOR loop (numeric and cursor)

Each loop has a loop boundary (begin and end statements) and a loop body The loop body should be indented from the

Trang 15

boundary (again, I recommend three spaces of indentation)

As with the IF statement, you can either choose to leave the LOOP reserved word at the end of the line containing the WHILE and FOR statements or place it on the next line I prefer the latter, because then both the LOOP and END LOOP reserved words appear at the same column position (indentation) in the program

Here are my recommendations for formatting your loops:

● The infinite or simple loop:

executable_statements;

END LOOP;

● The numeric and cursor FOR loops:

FOR for_index IN low_value high_value LOOP

3.3.3 Formatting Exception Handlers

PL/SQL provides a very powerful facility for dealing with errors An entirely separate exception section contains one or more "handlers" to trap exceptions and execute code when that exception occurs Logically, the exception section is structured like a conditional CASE statement (which, by the way, is not supported by PL/SQL)

As you might expect, the format for the exception section should resemble that of an IF statement Here is a general example of the exception section:

Trang 16

otherwise_code;

END;

Instead of an IF or ELSIF keyword, the exception handler uses the word WHEN In place of a condition (Boolean

expression), the WHEN clause lists an exception name followed by a THEN and finally the executable statements for that exception In place of ELSE, the exception section offers a WHEN OTHERS clause

Follow these guidelines:

● Indent each WHEN clause in from the EXCEPTION keyword that indicates the start of the exception section, as I've shown above Place the THEN directly below the WHEN

● Indent all the executable statements for that handler in from the THEN keyword

● Place a blank line before each WHEN (except for the first).

SQL Statements

Trang 17

Previous: 3.1 Fundamentals

of Effective Layout

Chapter 3 Effective Coding Style

Next: 3.3 Formatting Control Structures

3.2 Formatting SQL Statements

Because PL/SQL is an extension to the SQL language, you can place SQL statements directly in your PL/SQL

programs You can also define cursors based on SELECT statements This section summarizes my suggestions for formatting SQL statements and cursors for maximum readability

PL/SQL supports the use of four SQL DML (Data Manipulation Language) statements: INSERT, UPDATE, DELETE, and SELECT Each of these statements is composed of a series of "clauses," as in the WHERE clause and the ORDER

BY clause SQL statements can be very complex, to say the least Without a consistent approach to indentation and alignment inside these statements, you can end up with a real mess I have found the following guidelines useful: Right-align the reserved words for the clauses against the DML statement.

I recommend that you visually separate the SQL reserved words which identify the separate clauses from the application-specific column and table names The following table shows how I use right-alignment on the reserved words to create a vertical border between them and the rest of the SQL statement:

SELECT FROM

WHERE AND OR GROUP BY

HAVING AND OR ORDER BY

INSERT INTO VALUES

INSERT INTO SELECT FROM WHERE

UPDATE SET WHERE

DELETE FROM WHERE

Here are some examples of this format in use:

SELECT last_name, first_name

FROM employee

WHERE department_id = 15

AND hire_date < SYSDATE;

Trang 18

SELECT department_id, SUM (salary) AS total_salary

FROM employee

GROUP BY department_id

ORDER BY total_salary DESC;

INSERT INTO employee

SET hire_date = SYSDATE

WHERE hire_date IS NULL

AND termination_date IS NULL;

Yes, I realize that the GROUP BY and ORDER BY keywords aren't exactly right-aligned to SELECT, but at least the primary words (GROUP and ORDER) are aligned Notice that within each of the WHERE and HAVING clauses I right-align the AND and OR Boolean connectors under the WHERE keyword

This right alignment makes it very easy for me to identify the different clauses of the SQL statement, particularly with extended SELECTs You might also consider placing a blank line between clauses of longer SQL statements (this is possible in PL/SQL, but is not acceptable in "native" SQL executed in SQL*Plus)

Don't skimp on the use of line separators.

Within clauses, such separation makes the SQL statement easier to read In particular, place each expression of the WHERE clause on its own line, and consider using a separate line for each expression in the select list of a SELECT statement Place each table in the FROM clause on its own line Certainly, put each separate

assignment in a SET clause of the UPDATE statement on its own line Here are some illustrations of these guidelines:

WHERE E.company_id = C.company_id

AND E.employee_id = SH.employee_id

AND E.hire_date > ADD_MONTHS (SYSDATE, -60);

UPDATE employee

SET hire_date = SYSDATE,

termination_date = NULL

WHERE department_id = 105;

NOTE: You can place blank lines inside a sql statement when you are coding that sql from within a pl/

sql block You may not, on the other hand, embed white space in sql statements you are executing from

the sql*Plus command line

Trang 19

Use meaningful abbreviations for table and column aliases

It drives me crazy when a query has a six-table join and the tables have been assigned aliases A, B, C, D, E, and

F How can you possibly decipher the WHERE clause in the following SELECT?

SELECT select list

FROM employee A, company B, history C, bonus D,

profile E, sales F

WHERE A.company_id = B.company_id

AND A.employee_id = C.employee_id

AND B.company_id = F.company_id

AND A.employee_id = D.employee_id

AND B.company_id = E.company_id;

With more sensible table aliases (including no tables aliases at all where the table name was short enough already), the relationships are much clearer:

SELECT select list

FROM employee EMP, company CO, history HIST, bonus,

profile PROF, sales

WHERE EMP.company_id = CO.company_id

AND EMP.employee_id = HIST.employee_id

AND CO.company_id = SALES.company_id

AND EMP.employee_id = BONUS.employee_id

AND CO.company_id = PROF.company_id;

Previous: 3.1 Fundamentals

of Effective Layout

Next: 3.3 Formatting Control Structures

Trang 20

Using Comments Effectively

Documenting the Entire Package

You can learn everything about a programming language its syntax, high-performance tips, and advanced features and still write programs that are virtually unreadable, hard to maintain, and devilishly difficult to debug even by you, the author You can be very smart and very clever, and yet develop applications that obscure your talent and accomplishments

This chapter addresses the "look-and-feel" of your code the aesthetic aspect of programming I am sure that you have all experienced the pleasure of reading well-structured and well-formatted code You have also probably experienced a pang of jealousy at that programmer's style and effort,

wondering where she or he found the time to do it right Developers always experience a feeling of intense pride and satisfaction from carefully and artfully designing the visual layout of their code Yet few of us take the time to develop a style and use it consistently in our work

Of course, the impact of a coding style goes well beyond the personal satisfaction of any individual

A consistent, predictable approach to building programs makes it easier to debug and maintain that code If everyone takes her own approach to structuring, documenting, and naming her code, every program becomes its own little pool of quicksand It is virtually impossible for another person to put

in a foot and test the water (find the source of a problem, analyze dependencies, etc.) without being pulled under

I discuss the elements of an effective coding style in the PL/SQL language at this juncture, before we get to any code, for two reasons:

Trang 21

● To drive home the point that if you are going to adopt a coding style which will improve the readability and maintainability of your application, you need to do it at the beginning of your project Programming style involves an attention to detail that can be built only during the construction process You are not going to go back into existing code and modify the

indentation, case, and documentation format after the project is done

● To provide an explanation for the format and style which I employ throughout the book

While I can't promise that every line of code in the book will follow all of the guidelines in this chapter, I hope that you will perceive a consistent style that is easy on the eye and helpful

in aiding comprehension

Views on effective coding style are often religious in nature (similar to programmers' ideas on the use

of GOTO) that is, based largely on faith instead of rationality I don't expect you to agree with everything in this chapter (actually, in a number of places I suggest several alternatives) Such

unanimity is unrealistic and unnecessary Rather, I hope that this chapter gets you thinking about the style in your own programming

3.1 Fundamentals of Effective Layout

There is really just one fundamental objective of code layout:

Reveal and reinforce the logical structure of your program.

You could come up with ways of writing your code that are very pleasing to the eye, but doing so is less important than choosing a format that shows the structure and intent of the program

It is easy to address the topic of effective code layout for PL/SQL because it is such a well structured language It benefits greatly from Ada's block structure approach Each control construct, such as IF and LOOP, has its own terminator keyword, such as END IF and END LOOP Each logical block of code has an explicit beginning statement and an associated ending statement This consistent and natural block style lends itself easily and naturally to standards for indentation and whitespace, which further expose the structure of the code

3.1.1 Revealing Logical Structure with Indentation

Indentation is one of the most common and effective techniques used to display a program's logic via format As illustrated in the following examples, programs that are indented are easier to read than those that are not indented, although programs that use excessive indentation are not much more readable than unindented programs Here is an unindented IF statement:

Trang 22

"logical" indentation a tab can be equivalent to three spaces in one editor and eight in another I suggest avoiding the use of tabs altogether.)

I have found that a three-space indentation not only adequately reveals the logical structure of the code but also keeps the statements close enough together to read comfortably And, with deeply nested structures, you won't run off the right margin as quickly! Here is the three-space indented version of the previous nested IF statement:

The rest of this chapter presents specific techniques that I have found to be essential in writing

attractive, readable code that reveals the logic of my programs

3.1.2 Using Case to Aid Readability

PL/SQL code is made up of many different components: variables, form items, report fields,

procedures, functions, loops, declarations, control elements, etc But they break down roughly into two types of text: reserved words and application-specific names or identifiers

Reserved words are those names of language elements that are reserved by PL/SQL and have a special meaning for the compiler Some examples of reserved words in PL/SQL are:

WHILE

Trang 23

BEGIN

TO_CHAR

Application-specific identifiers are the names that you, the programmer, give to data and program

structures that are specific to your application and that vary from system to system

The compiler treats these two kinds of text very differently You can improve the readability of your code greatly by reflecting this difference in the way the text is displayed Many developers make no distinction between reserved words and application-specific identifiers Consider the following lines

3.1.3 The UPPER-lower Style

You can easily solve this problem by adopting a guideline for using a mix of upper- and lowercase to your code I have recoded my previous example below, this time using the UPPER-lower style: all reserved words are written in UPPERCASE and all application names are kept in lowercase:

Trang 24

Using a mixture of upper- and lowercase words increases the readability of the code by giving a sense

of dimension to the code The eye can more easily cruise over the text and pick the different

syntactical elements of each statement The uppercase words act as signposts directing the activity in the code You can focus quickly on the lowercase words for the application-specific content

Consistent use of this method makes the program listings more attractive and accessible at a glance

3.1.4 Formatting Single Statements

Most of your code consists of individual statements, such as assignments, calls to modules, and

declarations A consistent approach to formatting and grouping such statements will improve the readability of your program as a whole This section suggests some guidelines

3.1.4.1 Use at most one statement per line

As we discussed in Chapter 2, PL/SQL Language Fundamentals, PL/SQL uses the semicolon (;) as the logical terminator for a statement As a result you can have more than one statement on a line and you can continue a single executable statement over more than one line You will sometimes be

tempted to place several statements on a single line, particularly if they are very simple Consider the following line:

new_id := 15; calc_total (new_id); max_dollars := 105 *

sales_adj;

It is very difficult to pick out the individual statements in this line, in addition to the fact that a

procedure is called in the middle of the line By placing each statement on its own line you mirror the complexity of a program the simple lines look simple and the complex statements look complex and reinforce the top-to-bottom logic of the program:

new_id := 15;

calc_total (new_id);

max_dollars := 105 * sales_adj;

You can scan the left margin (which will move left and right depending on the logic and

corresponding indentation) and know that you are reviewing all the lines of code

3.1.4.2 Use whitespace inside a statement

You can use all the indentation and blank lines you want to reveal the logic of a program and still end

up with some very dense and unreadable code It is also important to employ whitespace within a single line to make that one statement more comprehensible Here are two general rules I employ in

my code:

● Always include a space between every identifier and separator in a statement Instead of this:

Trang 25

WHILE(total_sales<maximum_sales AND company_type='NEW')LOOP

write this:

calc_totals (company_id, LAST_DAY (end_of_year_date), total_type);

3.1.5 Formatting Your Declarations

The declaration section declares the local variables and other structures to be in your PL/SQL block This section comes right at the top of the block, so it sets the first impression for the rest of the

program If the declaration section has no apparent order and is poorly formatted, it is unlikely that anything else in that program will be easily understood

The declaration section in PL/SQL can contain many different kinds of declarations: simple, scalar variables; complex data structures like records and tables; exceptions; even entire subprograms which exist only in that program

The following sections give some guidelines for creating your declaration statements

3.1.5.1 Place one declaration on each line

You will be particularly tempted to "double up" declarations on a single line because, in general, declarations are very short in length Resist that temptation! Which of the following sets of

declarations would you prefer to try to understand at a glance?

Tiêu đề	Oracle PL/SQL Language Pocket Reference- P9
Trường học	Unknown University
Chuyên ngành	Computer Science
Thể loại	Pocket Reference
Năm xuất bản	Unknown Year
Thành phố	Unknown City

Định dạng
Số trang	50
Dung lượng	211,69 KB