BEGIN
/* 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);
END LOOP;
END LOOP;
END;
The problem with these comments is precisely that they do all start in the first column, regardless of
the code they describe. The most glaring example of this formatting "disconnect" comes in the inner
loop, repeated below:
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);
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
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
/* 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');
/*
|| 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);
END LOOP;
END LOOP;
END;
END LOOP;
END LOOP;
END;
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:
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
DECLARE
Assume a maximum string length of 1000 for a line
of text.
text_line VARCHAR2 (1000);
len_text NUMBER;
/*
|| Variables used to keep track of string scan:
|| atomic_count - running count of atomics scanned.
|| still_scanning - Boolean variable controls WHILE
loop.
*/
atomic_count NUMBER := 1;
still_scanning BOOLEAN;
BEGIN
Let's recast this declaration section using my proposed guideline: a comment for each declaration
statement. In the result shown below, the declaration section is now longer than the first version, but
it uses whitespace more effectively. Each declaration has its own comment, set off by a blank line if a
single-line comment:
DECLARE
/* Assume a maximum string length of 1000 for a line
of text. */
text_line VARCHAR2 (1000);
/* Calculate length of string at time of declaration */
len_string NUMBER;
/* Running count of number of atomics scanned */
atomic_count NUMBER := 1;
/* Boolean variable that controls WHILE loop */
still_scanning BOOLEAN ;
BEGIN
Previous: 3.5 Formatting
Packages
Oracle PL/SQL
Programming, 2nd Edition
Next: 3.7 Documenting the
Entire Package
3.5 Formatting Packages
Book Index
3.7 Documenting the Entire
Package
The Oracle Library
Navigation
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Copyright (c) 2000 O'Reilly & Associates. All rights reserved.
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Previous: 3.4 Formatting
PL/SQL Blocks
Chapter 3
Effective 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:
PACKAGE rg_select
IS
list_name VARCHAR2(60);
PROCEDURE init_list
(item_name_in IN VARCHAR2,
fill_action_in IN VARCHAR2 := 'IMMEDIATE');
PROCEDURE delete_list;
PROCEDURE clear_list;
END rg_select;
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
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
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.
Previous: 3.4 Formatting
PL/SQL Blocks
Oracle PL/SQL
Programming, 2nd Edition
Next: 3.6 Using Comments
Effectively
3.4 Formatting PL/SQL
Blocks
Book Index
3.6 Using Comments
Effectively
The Oracle Library
Navigation
Copyright (c) 2000 O'Reilly & Associates. All rights reserved.
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Previous: 3.3 Formatting
Control Structures
Chapter 3
Effective Coding Style
Next: 3.5 Formatting
Packages
3.4 Formatting PL/SQL Blocks
As I've outlined in Chapter 2, every PL/SQL program is structured as a block containing up to four
sections:
● Header
● Declaration section
● Executable section
● Exception section
The PL/SQL block structure forms the backbone of your code. A consistent formatting style for the
block, therefore, is critical. This formatting should make clear these different sections. (See
Chapter
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)
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
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;
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.
Previous: 3.3 Formatting
Control Structures
Oracle PL/SQL
Programming, 2nd Edition
Next: 3.5 Formatting
Packages
3.3 Formatting Control
Structures
Book Index
3.5 Formatting Packages
The Oracle Library
Navigation
Copyright (c) 2000 O'Reilly & Associates. All rights reserved.
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Previous: 3.2 Formatting
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.
3.3.1 Formatting IF Statements
This conditional construct comes in three flavors:
IF <expression>
END IF;
IF <expression>
ELSE
END IF;
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
IF <expression>
THEN
executable_statements;
END IF;
IF <expression> THEN
executable_statements
END IF;
IF <expression>
THEN
executable_statements;
ELSE
else_executable_statements;
END IF;
IF <expression> THEN
executable_statements
ELSE
else_executable_statements;
END IF;
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
IF <expression>1
THEN
executable_statements1;
ELSEIF <expression2>
THEN
executable_statements2;
ELSEIF <expressionN>
THEN
executable_statementsN;
ELSE
else_executable_statements;
END IF;
IF <expression>1 THEN
executable_statements1;
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:
IF max_sales > 2000 THEN
notify_accounting ('over_limit');
RAISE FORM_TRIGGER_FAILURE;
END IF;
This code has proper IF statement indentation with THEN on the next line:
IF max_sales > 2000
THEN
notify_accounting ('over_limit');
RAISE FORM_TRIGGER_FAILURE;
END IF;
3.3.2 Formatting Loops
You are going to be writing many loops in your PL/SQL programs, and they will usually surround some of the most
complicated code in your application. For this reason, the format you use to structure your loops will make a critical
difference in the overall comprehensibility of your programs.
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
Please purchase PDF Split-Merge on www.verypdf.com to remove this watermark.
Không có nhận xét nào:
Đăng nhận xét