Re: Useful Scripts

[Ray Ontko <rayo@ONTKO.COM>]

> Need helpful hints in writting good SQR code. Any help is highly appreciated.
> Thanks
> SPR

Suresh, SQR netters,

Here's a start at SQR naming conventions and coding standards.
I mean for this to get the discussion rolling, so please
offer additions, alternatives, and comments.

Ray

-----


SQR Coding Guidelines

January 7, 1996

Ray Ontko


Purpose

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


Overview

This document addresses the following areas of SQR program development:

  o  File Naming
  o  Variable Naming
  o  Reusable Program Modules
  o  Passing Parameters between Procedures
  o  Internal Documentation


File Naming

All SQR program files should be named xxx.sqr.

Include files should be named xxx.sqh, where xxx is the name of the module
defined in the file, or the primary module if several are defined.

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

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


Reusable Program Modules

All reusable program modules should be created as .sqh files.  Each sqh file
should contain one callable procedure (it may also contain procedures that are
called exclusively by the procedure).  The file should be named
<procedure_name>.sqh.

Any procedures which are used exclusively within the reusable program module
(i.e., they are not also reusable) should be named <procedure_name>_xxx
(where <procedure_name> is the name of the main procedure in the file) to
avoid naming conflicts with user-defined procedures or other reusable
procedures.

Avoid using global variables in reusable program modules.  If these are needed
for persistence between calls to the module, all such global variables should
be named <procedure_name>_xxx (starting with # or $ or &, of course).

Reusable program modules used by a program should be referenced using
the "#include" directive immediately after "end-report".

All reusable program modules should be wrappered with:

#ifndef __<file_name>__
#define __<file_name>__ <file_name>
...
#endif

Any "#include" needed by a reusable program module should be added after the
"#define __<file_name>__ <file_name>" shown above.


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


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 "!--".