Ray Ontko & Co.
Services | Products | Library | Careers News | About Us | Contact Us | Search | Site Map

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.


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


This document addresses the following areas of SQR program development:

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},
"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".


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

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:


begin-procedure proc_a
end-procedure proc_a

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
before including the reusable procedure file, for each procedure you need.

begin-procedure proc_a
end-procedure proc_a

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:

begin-procedure proc_a
do proc_b
end-procedure proc_a

begin-procedure proc_b
end-procedure proc_b

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)

Copyright © 1999, Ray Ontko & Co. Last updated: Tuesday, February 27, 2007
Careers Library Products Services Site Map Search Contact Us About Us News