The object of an effective coding style is to make the program more understandable and maintainable. Most programs will benefit from documentation which explains what is going on inside those programs. There are two forms of code documentation: external and internal. External documentation is descriptive information about a program which is written and stored separately from the program itself. Internal documentation, also known as inline documentation or comments, is placed within the program itself, either at the program level or the statement level. (For an introduction to inline documentation and the types of PL/SQL comments, see the section called "Comments" in Chapter 2.)

The best kind of internal documentation derives from your programming style. If you apply many of the guidelines in this chapter and throughout this book, you will be able to write code which is, to a great extent, self-documenting. Here are some general tips:

• Write straightforward code that avoids clever tricks.

   

• Think of names for variables and modules that accurately describe their purpose.

   

• Use named constants instead of literal values.

   

• Employ a clean, consistent layout.

   

Do all these things and more, and you will find that you need to write fewer comments to explain your code.

Reducing the need for comments is important. Few developers make or have the time for extensive documentation in addition to their development efforts, and, more importantly, many comments tend to duplicate the code. This raises a maintenance issue because those comments will have to be changed when the code is changed.

While it is my hope that after reading this book you will write more self-documenting code, there is little doubt that you will still need to comment your code. The following example shows the use of single- and multiline comments in PL/SQL:

PROCEDURE calc_totals (company_id IN NUMBER,--The company key
                       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.
*/
FOR emp_rec IN emp_cur (ADD_MONTHS (SYSDATE, -60))
LOOP
   apply_bonus (emp_rec.employee_id);
   send_notification (emp_rec.employee_id);
END LOOP;
 
-- IF :SYSTEM.FORM_STATUS = 'CHANGED' THEN COMMIT; END IF;
 
FUNCTION display_user 
   (user_id IN NUMBER /* Must be valid ID */, user_type IN VARCHAR2)

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.

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

When you write a comment you (theoretically) explain what your code is meant to accomplish. If you find it difficult to come up with that explanation, there is a good chance that you lack a full 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.

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 re-enter!');
 
   -- Reset the counter to zero.
   :employee.comp_counter := 0;
 
   -- Raise the exception to stop trigger processing.
   RAISE FORM_TRIGGER_FAILURE;
END IF;

None of these comments add anything to the comprehension of the code. Each comment simply restates the line of code, which in most cases is self-explanatory.

Avoid adding comments simply so that you can say, "Yes, I documented my code!" Rely as much as possible on the structure and layout of the code itself to express the meaning of the program. Reserve your comments to explain the Why of your code: What business rule is it meant to implement? Why did you need to implement a certain requirement in a certain way?

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;

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:

PROCEDURE empty_list IS

BEGIN

:GLOBAL.num_elements := 0;

END;

Then to empty a list you would not need any comment at all. You could simply include the statement:

empty_list;

and the meaning would be perfectly clear.

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

/*
===========================================================
| Parameter          Description                          |
|                                                         |
| company_id         The primary key to company           |
| start_date         Start date used for date range       |
| end_date           End date for date range              |
===========================================================
*/

The right-justified vertical lines and column formatting for the parameters require way too much effort to enter and maintain. What happens if you add a parameter with a very long name? What if you need to write a longer description? A simpler and more maintainable version of this comment might be:

/*
===========================================================
| 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 like to use the following format for my block comments:

/*
|| I put the slash-asterisk that starts the comment on a line all by
|| itself. Then I start each line in the comment block with a double

|| vertical bar to highlight the presence of the comment. Finally,

|| I place the asterisk-slash on a line all by itself.

*/

On the negative side, the vertical bars have to be erased whenever I reformat the lines, but that isn't too much of an effort. On the positive side, those vertical bars make it very easy for a programmer who is scanning the left side of the code to pick out the comments.

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.

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;
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
   /* 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;

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:

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

Before / for each row trigger

create table t_update_before_each_row (
txt varchar2(10)
);
create table log (
txt varchar2(20)
);
create trigger update_before_each_row
before update on t_update_before_each_row
for each row
begin
:new.txt := upper(:new.txt);
insert into log values ('old: ' || :old.txt);
insert into log values ('new: ' || :new.txt);
end update_before_each_row;
/

insert into t_update_before_each_row values('one');
insert into t_update_before_each_row values('two');
insert into t_update_before_each_row values('three');
insert into t_update_before_each_row values('four');

update t_update_before_each_row set txt = txt || txt
where substr(txt,1,1) = 't';

select * from t_update_before_each_row;

one
TWOTWO
THREETHREE
four

select * from log;

old: two
new: TWOTWO
old: three
new: THREETHREE

drop table t_update_before_each_row;
drop table log;

After / for each row trigger

create table t_update_after_each_row (
txt varchar2(10)
);
create table log (
txt varchar2(20)
);
create trigger update_after_each_row
after update on t_update_after_each_row
for each row
begin
-- :new.txt := upper(:old.txt); -- ORA-04084: cannot change NEW values for this trigger type
insert into log values ('old: ' || :old.txt);
insert into log values ('new: ' || :new.txt);
end update_after_each_row;
/

insert into t_update_after_each_row values('one');
insert into t_update_after_each_row values('two');
insert into t_update_after_each_row values('three');
insert into t_update_after_each_row values('four');

update t_update_after_each_row set txt = txt || txt
where substr(txt,1,1) = 't';

select * from t_update_after_each_row;

one
twotwo
threethree
four

select * from log;

old: two
new: twotwo
old: three
new: threethree

drop table t_update_after_each_row;
drop table log;

Table level trigger

create table t_update_before (
txt varchar2(10)
);
create table log (
txt varchar2(20)
);
create trigger update_before
before update on t_update_before
begin
-- :new.txt := upper(:old.txt); -- ORA-04082
insert into log values ('update trigger');
end update_before;
/

insert into t_update_before values('one');
insert into t_update_before values('two');
insert into t_update_before values('three');
insert into t_update_before values('four');

update t_update_before set txt = txt || txt
where substr(txt,1,1) = 't';

select * from t_update_before;

one
twotwo
threethree
four

select * from log;

update trigger

update t_update_before set txt = txt || txt
where txt = 'no update';

select * from log;

update trigger
update trigger

drop table t_update_before;
drop table log;

Order of execution

可以用两种方式创建MySQL账户：

·         使用GRANT语句

·         直接操作MySQL授权表

最好的方法是使用GRANT语句，因为这样更精确，错误少。从MySQL 3.22.11起提供了GRANT；其语法见13.5.1.3节，“GRANT和REVOKE语法”。

创建账户的其它方法是使用MySQL账户管理功能的第三方程序。phpMyAdmin即是一个程序。

下面的示例说明如何使用MySQL客户端程序来设置新用户。假定按照2.9.3节，“使初始MySQL账户安全”描述的 默认值来设置权限。这说明为了更改，你必须以MySQL root用户连接MySQL服务器，并且root账户必须有mysql数据库的INSERT权限和RELOAD管理权限。

首先，使用MySQL程序以MySQL root用户来连接服务器：

shell> MySQL --user=root MySQL

如果你为root账户指定了密码，还需要为该MySQL命令和本节中的其它命令提供--password或-p选项。

以root连接到服务器上后，可以添加新账户。下面的语句使用GRANT来设置四个新账户：

mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'localhost'

    ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;

mysql> GRANT ALL PRIVILEGES ON *.* TO 'monty'@'%'

    ->     IDENTIFIED BY 'some_pass' WITH GRANT OPTION;

mysql> GRANT RELOAD,PROCESS ON *.* TO 'admin'@'localhost';

mysql> GRANT USAGE ON *.* TO 'dummy'@'localhost';

用GRANT语句创建的账户有下面的属性：

·         其中两个账户有相同的用户名monty和密码some_pass。两个账户均为超级用户账户，具有完全的权限可以做任何事情。一个账户 ('monty'@'localhost')只用于从本机连接时。另一个账户('monty'@'%')可用于从其它主机连接。请注意monty的两个账户必须能从任何主机以monty连接。没有localhost账户，当monty从本机连接时，mysql_install_db创建的localhost的匿名用户账户将占先。结果是，monty将被视为匿名用户。原因是匿名用户账户的Host列值比'monty'@'%'账户更具体，这样在user表排序顺序中排在前面。(user表排序的讨论参见5.7.5节，“访问控制, 阶段1：连接核实”）。

·         一个账户有用户名admin，没有密码。该账户只用于从本机连接。授予了RELOAD和PROCESS管理权限。这些权限允许admin用户执行mysqladmin reload、mysqladmin refresh和mysqladmin flush-xxx命令，以及mysqladmin processlist。未授予访问数据库的权限。你可以通过GRANT语句添加此类权限。

·         一个账户有用户名dummy，没有密码。该账户只用于从本机连接。未授予权限。通过GRANT语句中的USAGE权限，你可以创建账户而不授予任何权限。它可以将所有全局权限设为'N'。假定你将在以后将具体权限授予该账户。

除了GRANT，你可以直接用INSERT语句创建相同的账户，然后使用FLUSH PRIVILEGES告诉服务器重载授权表：

shell> mysql --user=root mysql

mysql> INSERT INTO user

    ->     VALUES('localhost','monty',PASSWORD('some_pass'),

    ->     'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');

mysql> INSERT INTO user

    ->     VALUES('%','monty',PASSWORD('some_pass'),

    ->     'Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y','Y');

mysql> INSERT INTO user SET Host='localhost',User='admin',

    ->     Reload_priv='Y', Process_priv='Y';

mysql> INSERT INTO user (Host,User,Password)

    ->     VALUES('localhost','dummy','');

mysql> FLUSH PRIVILEGES;

当你用INSERT创建账户时使用FLUSH PRIVILEGES的原因是告诉服务器重读授权表。否则，只有重启服务器后更改方会被注意到。使用 GRANT，则不需要使用FLUSH PRIVILEGES。

用INSERT使用PASSWORD()函数是为了加密密码。GRANT语句为你加密密码，因此不需要PASSWORD()。

'Y'值启用账户权限。对于admin账户，还可以使用更加可读的INSERT扩充的语法（使用SET）。

在为dummy账户的INSERT语句中，只有user表中的Host、User和Password列记录为指定的值。没有一个权限列为显式设置，因此MySQL将它们均指定为 默认值'N'。这样等同于GRANT USAGE的操作。

请注意要设置超级用户账户，只需要创建一个权限列设置为'Y'的user表条目。user表权限为全局权限，因此其它 授权表不再需要条目。

下面的例子创建3个账户，允许它们访问专用数据库。每个账户的用户名为custom，密码为obscure。

要想用GRANT创建账户，使用下面的语句：

shell> MySQL --user=root MySQL

shell> mysql --user=root mysql

mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP

    ->     ON bankaccount.*

    ->     TO 'custom'@'localhost'

    ->     IDENTIFIED BY 'obscure';

mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP

    ->     ON expenses.*

    ->     TO 'custom'@'whitehouse.gov'

    ->     IDENTIFIED BY 'obscure';

mysql> GRANT SELECT,INSERT,UPDATE,DELETE,CREATE,DROP

    ->     ON customer.*

    ->     TO 'custom'@'server.domain'

    ->     IDENTIFIED BY 'obscure';

这3个账户可以用于：

·         第1个账户可以访问bankaccount数据库，但只能从本机访问。

·         第2个账户可以访问expenses数据库，但只能从主机whitehouse.gov访问。

·         第3个账户可以访问customer数据库，但只能从主机server.domain访问。

要想不用GRANT设置custom账户，使用INSERT语句直接修改 授权表：

shell> mysql --user=root mysql

mysql> INSERT INTO user (Host,User,Password)

    ->     VALUES('localhost','custom',PASSWORD('obscure'));

mysql> INSERT INTO user (Host,User,Password)

    ->     VALUES('whitehouse.gov','custom',PASSWORD('obscure'));

mysql> INSERT INTO user (Host,User,Password)

    ->     VALUES('server.domain','custom',PASSWORD('obscure'));

mysql> INSERT INTO db

    ->     (Host,Db,User,Select_priv,Insert_priv,

    ->     Update_priv,Delete_priv,Create_priv,Drop_priv)

    ->     VALUES('localhost','bankaccount','custom',

    ->     'Y','Y','Y','Y','Y','Y');

mysql> INSERT INTO db

    ->     (Host,Db,User,Select_priv,Insert_priv,

    ->     Update_priv,Delete_priv,Create_priv,Drop_priv)

    ->     VALUES('whitehouse.gov','expenses','custom',

    ->     'Y','Y','Y','Y','Y','Y');

mysql> INSERT INTO db

    ->     (Host,Db,User,Select_priv,Insert_priv,

    ->     Update_priv,Delete_priv,Create_priv,Drop_priv)

    ->     VALUES('server.domain','customer','custom',

    ->     'Y','Y','Y','Y','Y','Y');

mysql> FLUSH PRIVILEGES;

前3个INSERT语句在user表中加入条目，允许用户custom从各种主机用给定的密码进行连接，但不授予全局权限(所有权限设置为 默认值'N')。后面3个INSERT语句在user表中加入条目，为custom授予bankaccount、expenses和customer数据库权限，但只能从合适的主机访问。通常若直接修改 授权表，则应告诉服务器用FLUSH PRIVILEGES重载授权表，使权限更改生效。

如果你想要让某个用户从给定域的所有机器访问(例如，mydomain.com)，你可以在账户名的主机部分使用含‘%’通配符的GRANT语句：

mysql> GRANT ...

    ->     ON *.*

    ->     TO 'myname'@'%.mydomain.com'

    ->     IDENTIFIED BY 'mypass';

要想通过直接修改授权表来实现：

mysql> INSERT INTO user (Host,User,Password,...)

    ->     VALUES('%.mydomain.com','myname',PASSWORD('mypass'),...);

mysql> FLUSH PRIVILEGES;