SQR Coding Standards and Naming Conventions

Copyright © 1997, Ray Ontko & Company. This document may be freely copied and distributed as long as it retains this copyright notice.

Purpose

This document provides recommended naming conventions and coding guidelines for SQR programs.

Contents

This document addresses the following areas of SQR program development:

• File Naming
  
• Variable Naming
  
• Table Name Aliasing
  
• Indention and Spacing
  
• Comments
  
• Procedure Naming
  
• Procedure Ordering
  
• SQL Formatting
  
• Reusable Procedures
  
• Passing Parameters between Procedures
  
• Using Goto
  
• Internal Documentation

File Naming

All SQR program files should be named xxx.sqr.

All #include files should be named xxx.sqh. If the #include file contains modules that are specific to a particular program, the "xxx" should should match the name of the program. If the #include file contains routines that are shared by a number of programs for a project or application, the file should be named abc.sqh, where "abc" corresponds to the name of the project.

Max files (-m files) for a given program should be named xxx.sqm, where xxx.sqr is the name of the program they are used with.

Under Unix, all file names should be all lower-case.

Variable Naming

Avoid use of the hyphen "-" in variable names. Use the underscore "_" instead. The hyphen is sometimes confusing (e.g., #count-1 is VERY different from #count - 1).

Avoid use of capitalization in variable names. Use the underscore "_" character to separate different "words" within the variable name.

Database table and column names when used in variable names or procedure names should not be abbreviated or changed except where necessary. This more clearly associates the variable or procedure with the source column or table, and makes it easier to search for affected code when changing a table or column. For example, if a column is named "invoice_total", we might have a variable for storing the sum of all invoice totals called #sum_invoice_total or #invoice_total_sum, but not #sum_invoice or #total_all_invoices.

Avoid abbreviations in variable names unless there has been a standard abbreviation identified for the project.

Table Name Aliasing

Table aliases are only needed from time to time. When this need arises, we support two methods of aliasing:

1. Abbreviations of the name of the table
2. First letter(s) of the table name(s)

Which method will best satisfy the requirements of that section of code is left to the programmer's descretion. We do not support the straight numbering/lettering of aliases (1,2,3 or a,b,c....).

Indentation and Spacing

No line should continue past the 80th position in the file for the sake of portability.

Each level should have an indentation of 3 spaces.

When continuing a statement, the continuation should be indented either 3 spaces, or enough to align with semantically equivalent portions of the previous line. i.e.

let {varname} = {statements.............}
                {continued statements...}

do {procedure name} ({arg1},{arg2}....{argx},
                     {argx+1}..........)

"begin-setup", "begin-program", "begin-report", "begin-procedure", and "begin-select" sections should begin at the left margin and their contents should not be indented.

"begin-sql" sections should follow the above rule unless they are contained within an "if" structure, in which case the "begin-sql" section is indented appropriately to the "if".

"if", "while", and "evaluate" sections increase the indentation by 3 spaces. "else", "end-if", "end-while", "when", "when-other", and "end-evaluate" should have the same indentation as their corresponding "if", "while", or "evaluate".

Comments

Each "begin-procedure" should be preceded by a comment line, 72 characters long, of dashes ending in a space and the right justified name of the procedure. i.e.

!------------------------------------------------------------- proc_name

Procedure Naming

Avoid use of the hyphen "-" in procedure names. Use the underscore "_" instead.

Avoid use of capitalization in procedure names. Use the underscore "_" character to separate different "words" within the procedure name.

Avoid abbreviations in procedure names unless there have been standard abbreviations identified for the project.

Reusable Procedures should be named {project abbreviation}_{descriptive name}

Section Ordering

Procedures should be in the order

  begin-setup
  begin-program
  begin-heading
  begin-footing
  begin-procedure {main_procedure_name}
  .....
  {continuing from highest to lowest level}
  .....
  .....

SQL Formatting

While we allow a certain amount of flexibility for each individual on the exact structure of SQL statements, there are certain criteria we expect to be adhered to. Among these are:

• No "moves" unless necessary. In other words, don't MOVE every &variable into a $variable or #variable; only move those that are required by the logic of your program.
• Processing code should be found directly above the "from".
• All key words in the structure should stand out.
• Punctuation (like commas) should fade into the structure.
• Sub SQL statements should follow the same form, but indented.
• "There are 2 rules of precedence. Multiply before you add and use parentheses everywhere else." (paraphrase from O'Reilly and Assoc.)

Reusable Procedures

All reusable procedures should be created in .sqh files.

Avoid using global variables in reusable procedures. If these are needed to share data between between several related reusable procedures, all such global variables should be named <procedure_name>_xxx or <package_name>_xxx (starting with #, $ or &, of course).

Reusable procedure files needed by a program should be included using the "#include" directive immediately before "begin-program".

All reusable procedures should be wrappered with #ifndef, #define and #endif pre-processing directives in the following pattern to assure that the procedure will only be included once, even if the reusable procedures file accidentally gets included multiple times:

#IFNDEF DEF_PROC_A
#DEFINE DEF_PROC_A PROC_A
begin-procedure proc_a
...
end-procedure proc_a
#ENDIF

When a reusable procedure file contains several reusable procedures, you can reduce "bloating" by including only those procedures which you need. Wrap the reusable procedures with additional #ifdef and #endif pre-processing directives. In your code add a
#DEFINE INC_PROC_A PROC_A
before including the reusable procedure file, for each procedure you need.

#IFDEF INC_PROC_A
#IFNDEF DEF_PROC_A
#DEFINE DEF_PROC_A PROC_A
begin-procedure proc_a
...
end-procedure proc_a
#ENDIF
#ENDIF

Finally, if the reusable procedure (r.p) needs to call another r.p. in the reusable procedure file, then the second r.p. needs to physically exist after the first r.p. in the file, and the first r.p. needs an additional #define pre-processing directive in the following pattern:

#IFDEF INC_PROC_A
#IFNDEF DEF_PROC_A
#DEFINE DEF_PROC_A PROC_A
#DEFINE INC_PROC_B PROC_B
begin-procedure proc_a
...
do proc_b
...
end-procedure proc_a
#ENDIF
#ENDIF

#IFDEF INC_PROC_B
#IFNDEF DEF_PROC_B
#DEFINE DEF_PROC_B PROC_B
begin-procedure proc_b
...
end-procedure proc_b
#ENDIF
#ENDIF

Any "#INCLUDE" needed by a reusable program module should be added to the bottom of the file.

Passing Parameters between Procedures

All procedures implemented as external reusable program modules should pass all values into and out of the procedure using parameters (no global variables). Reusable procedures which pass no parameters should be declared LOCAL.

Procedures specific to a program may use global variables, but this practice is recommended only for the smallest of programs. These procedures should be declared within the program file (not #included).

Using GOTO

Using "goto" is considered harmful and shall be discouraged!

Internal Documentation

All programs and include files should include the following header:

!++
!
! Name
!
! xxx.sqr (or xxx.sqh)
!
! Description
!
! <a one or two sentence description>
!
! Parameters
!
! <describe the parameters>
!
! Notes
!
! <more notes about the program>
!
!--
!
! Modification History
!
! Name             Date        Comment
! ---------------  ----------  -----------------------------------------
! <name>           yyyy.mm.dd  Created
!

A simple program can be used to extract the information between the "!++" and the "!--".

Page maintainer: Ray Ontko (rayo@ontko.com)