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:

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

  write this:

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

• Use spaces to make module calls and their parameter lists more understandable. Instead of this:

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

  write this:

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

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?

DECLARE
   comp_type VARCHAR2(3); right_now DATE := SYSDATE; month_num INTEGER; 

or:

DECLARE
   comp_type VARCHAR2(3);
   right_now DATE := SYSDATE;
   month_num INTEGER; 

3.1.5.2 Ignore alignment for declarations

Many programmers like to align their declarations -- for example:

DECLARE
   company_name      VARCHAR2(30);
   company_id        INTEGER;

   employee_name     VARCHAR2(60);
   hire_date         DATE;
   termination_date  DATE;

   min_value         NUMBER;

I am not convinced of the value of declaration alignment. Although alignment makes it easier to scan down the datatypes, the datatype isn't nearly as important as the identifier, which is already left-justified. A commitment to alignment also raises all kinds of questions that consume a developer's time and thought processes: If you have one long variable name, do you have to move all the other datatypes out to match that datatype declaration? What about when you add a new, very long declaration into an existing section? Do you have to go back and add a tab or two to the existing declarations?

The elegance of alignment also breaks down when you include comments above individual declarations, as shown in the following example:

DECLARE
   company_name      VARCHAR2(30);
   /* Primary key into company table */
   company_id        INTEGER;

   employee_name     VARCHAR2(60);
   /* Date hired; must be no greater than today's date. */
   hire_date         DATE;
   termination_date  DATE;

   min_value         NUMBER;

When the comment text cuts across the vast spaces of the alignment tabs, it just makes the datatype look isolated from its identifier.

I believe that you are better off ignoring alignment for declarations.[1] Keep the elements of the declaration (datatype and default value) close to the identifier.

[1] I recognize, however, that many developers I respect greatly for their code quality and elegance differ with me strongly on this point.

3.1.6.1 Use indentation to offset all continuation lines under the first line.

This is the most important guideline. The best way to identify continuation lines is to use indentation to logically subsume those lines under the main or first line of the statement. The following call to generate_company_statistics is obscured because the continuation line butts right up against the left margin with the module name:

generate_company_statistics (company_id, last_year_date,
rollup_type, total, average, variance, budgeted, next_year_plan);

If I indent the continuation line, the relationship of the second line to the first becomes clear:

generate_company_statistics (company_id, last_year_date,
   rollup_type, total, average, variance, budgeted, next_year_plan);

This attempt to recode, however, shows that simply adding an indentation isn't always enough. While it is clear that the line starting with rollup_type "belongs" to the previous line, the relationship of the text on the continuation line to that of the first line is unclear. We need more than a simple call to "Indent." There are several possible approaches:

Indent module-call continuation lines to align all parameters vertically.

You can place a single parameter on each line for maximum clarity, or include more than one parameter on a line -- as long as they are properly indented. You can even break up the parameters so that related parameters go together on separate lines. If the name of the procedure is long and results in pushing the alignment column for parameters too far to the right, start the entire parameter list on the next line (indented) and then align all parameters against that second line. Here are some examples illustrating these rules:

gen_stats (company_id, last_year_date, rollup_type,
          total, average, variance, budgeted, next_year_plan);

gen_stats (company_id,
          last_year_date,
          rollup_type,
          total,
          average,
          variance,
          budgeted,
          next_year_plan);

gen_stats
   (company_id, last_year_date, rollup_type,
    total, average, variance, budgeted, next_year_plan);

I prefer the third alternative, in which all parameters are moved to the line following the name of the module. You can then place multiple parameters on the same line or place one parameter on each line, but the indentation is always and only the standard three spaces in from the start of the module name.

Make it very obvious that a statement is continued.

If a statement is not going to fit onto a single line, break up the statement so that it is quite obvious, with the most casual glance, that the first line could not possibly finish the statement. The following examples highlight this approach:

• The IN statement of a loop clearly needs its range:

  FOR month_index IN
     first_month .. last_month
  LOOP
     ...

• An assignment could not possibly end with a "+":

  q1_sales :=
     month1_sales +
     month2_sales +
     month3_sales;

• The last comma in the first line of parameters indicates that other parameters follow:

  generate_company_statistics
     (company_id, last_year_date,
      rollup_type, total, average, variance, budgeted, next_year_plan);