.
 

Enterprise Systems

banner-enterprise

     

Code Format Standards

How you format your code in your source code is an intensely personal issue. Most people use conventions that are imposed by corporate standards. But when there is no standard available then most programmers feel lost. They end up using a mish-mash of techniques that makes the resulting code hard to read. So it is important that every programmer develop a consistent and cohesive coding style that is easy to read and maintain.

 

There are two points of view to formatting. One is the developer’s view. The other is the maintainer’s view. A good standard should meet the needs of both views. There is really one fundamental reason for formatting your code: Reveal and reinforce the logical structure of your program.


Indentation

Indentation is one of the most common and effective ways to display a program’s logical structure. Programs that are indented are lot easier to read than those that are not. Please be aware that indentation is a double-edged sword. It is very easy to mislead with inconsistent indentation.

 

General Indentation Rules

  • Indent and align nested control structures, continuation lines, and embedded units consistently.
  • Distinguish between indentation for nested control structures and for continuation lines.
  • Use spaces for indentation, not the tab character (Nissen and Wallis, 1984)

Indentation Recommendations

The following indentation conventions are recommended. Note that the minimum indentation is described. More spaces may be required for the vertical alignment recommended in subsequent guidelines. 

  • Use three spaces as the basic unit of indentation for nesting.
  • Use three spaces as the basic unit of indentation for continuation lines.

 

 

 

 

This amount of spacing not only adequately reveals the logical structure of the code but also keeps the statements close enough together to read comfortably. You also don’t run off the edge of the page with deeply nested structures. Although you should try avoiding deeply nested structures, since most human brains can’t stack more that 5 items at a time.

  

Alignment

As mentioned above trying to keep programs pretty is a lot of work. Hence the following recommendations:

  • Do not try to align statements, operators etc. vertically. This not only takes up time, but also leads to realigning text continuously.
    Indent continuation lines the same three spaces.
  • Provide one declaration per line (at most).
  • Place the first parameter specification on a separate line from the function or procedure declaration.If any of the parameter types are forced beyond the line length limit, place the first parameter specification on a new line indented as for continuation lines.
  • Place one formal parameter specification per line.


Using Capitalization to Aid Readability

PL/SQL code is made up of many different components: variables, form items, report fields, procedures, functions, loops, etc. All these fall into two major categories: Reserved words and program specific identifiers. Reserved words are those language elements that are used by PL/SQL. They have special meaning to the compiler and hence are reserved. Program specific identifiers are the names that a programmer gives to the various components of program such as variables, constants, procedures etc.

The PL/SQL compiler treats these two types of text very differently. You can improve the readability of the code greatly by reflecting this difference in the way the text is displayed.

Using indentation highlights the logical structure of a program. To distinguish between reserved words and program specific identifiers, use of the upper and lowercase strategy is recommended. Use all UPPER case of reserved words and lower case of program specific identifiers. This increases the readability of the code.


Formatting Single Statements

Most of the programs consist of single statements. Consistent approach to formatting and grouping such statements will improve the readability of the program. The following are recommended rules.

  • Use at most one statement per line

    PL/SQL uses a logical line terminator, semicolon(;). This allows for placing more than one statement per line as well as continuing a single statement on multiple lines. 
    v_var1 := 0 ; lv_var2 := 1 ;      -- This is valid
    v_var1 := 0;                               -- But code this
    v_var2 := 1;                               -- way instead

  • Always include a space between an identifier and a separator.
    v_var1:=0;                                -- This is valid
    lv_var1 := 0;                              - But code this way for clarity.

  • Use spaces to make module calls and their parameter lists more understandable
    calc_totals(pv_company_id,pv_end_of_year_date);       -- Valid
    calc_totals (pv_company_id, pv_end_of_year_date);     -- Clearer


Formatting Declarations

Declaration section is used to declare local variables and other structures uses in the PL/SQL block. The following rules are recommended.

  • Place one declaration on each line. This follows the same logic that was described previously.
  • Keep declarations left justified with appropriate indentation.
  • Vertical alignment of declarations is a personal preference. But keeping declarations aligned is probably more trouble than it is worth.

Example of vertically aligned declaration:

lv_employee_count            INTEGER;
lv_employee_name             VARCHAR2;
lc_fulltime_hours   CONSTANT INTEGER    := 40; 

Example of declaration without vertical alignment 

lv_employee_count INTEGER;
lv_employee_name VARCHAR2;
lc_fulltime_hours CONSTANT INTEGER := 40; 


Formatting Multi-line Statements

As mentioned previously, PL/SQL’s logical line structure allows for very long strings of text for statements, which may not fit on a traditional line of 80 - 132 columns. So it is easy to spread statements like this across many lines, which makes it difficult to read. Here are some recommendations.

  • Use indentation to offset all continuation lines under the first line.
  • This is the most important guideline. By indenting the continuation lines the same 3 spaces that are recommended, they are subsumed under the first line.
  • Place the module name on a separate line from the parameters, Indent module-call continuation lines to align parameters vertically.
    Gen_stats

(pv_company_id,
pv_last_year_date,
pv_rollup_type,p
v_total) ;  

  • Make it obvious that a statement is continued
    FOR month_index IN                    

Lv_first_month .. lv_last_month
LOOP

gv_q1_sales :=

lv_month1_sales +
lv_month2_sales +
lv_month3_sales;

Gen Stats

pv_last_year_date,
pv_rollup_type,
pv_total) ;