| SQR Code Formatting | KEVIN RESCHENBERG
07-06-2004 |
Unlike PeopleCode, SQR does not force a particular coding format. Sometimes I wish
it did. You know the type:
BEGIN-PROCEDURE CALC-AMT
BEGIN-SELECT
COMPRATE &COMPRATE
COMP_FREQUENCY &COMP_FREQUENCY
LET #COMPRATE=&COMPRATE
LET $COMP_FREQ = &COMP_FREQUENCY
DO CALC-AMT-2 !CALCULATE AMOUNT
END-SELECT
END-PROCEDURE
BEGIN-PROCEDURE CALC-AMT-2
DISPLAY 'CALC-AMT-2'
IF $COMP_FREQ = 'M'
SHOW 'M'
LET #F = 12 !SET F TO 12
ELSE
IF $COMP_FREQ = 'Q'
SHOW 'Q'
LET #F = 4
MOVE 1.0005 TO #NUM
END-IF
END-IF
SHOW #NUM
LET ...
This example has it all: Inconsistent or no indentation, useless comments, mysterious
uncommented literals, DISPLAYs and SHOWs for debugging purposes, no separation between
sections and procedures, redundant assignments, and on and on. This example is
made up, but we've all seen these "features" in code. How can you maintain code
like this?
Rather than try to give a long list of "standards" or rules, let me reduce it down to just a few
very simple suggestions. There is, of course, no "correct" way to do this, but the following
are, in my opinion only, good ways of formatting code.
- Begin coding the following in column 1:
begin-program (-report), begin-procedure, begin-setup, begin-heading, begin-footing- Database column names in a SELECT block (this is required by SQR)
- Compiler directives:
#include, #ifdef, #define, etc.
- Comments, as appropriate
- No other elements other than the ones listed above should begin in column 1. Indent everything
else using a consistent number of spaces. (I use two spaces.)
- Indent one level under each of the
begin-
elements listed above and each
if, while, evaluate, when, begin-select, begin-sql.
The end should align with this keyword. Rule of thumb: Indent under
when and under anything that has an associated end- keyword.
- Indent within the SQL inside of a
begin-select. This means that the
SQL (FROM, WHERE) will be indented one level and the SQR code within the block will be indented an additional level.
- Don't use tabs for indentation. Use spaces instead.
- Use all upper case for the following:
- SQL clauses
- Database column names
#define constants- Literals, such as 'Y' and 'N'
- Use lower or mixed case for all other elements.
Here are the reasons for these suggestions. First, $THISISREALLYHARDTOREAD. Code in mixed or lower case
is easier to read in general. However, some
databases are case sensitive, so I suggest coding SQL in all caps. This also helps to set the SQL off
from the SQR code.
Indentation is very important for following the logic of a program. When you come to an if, you
often want to find the else or end-if
quickly. Without indentation, you need to scan every line...probably forgetting what it was you were looking for.
I place #define and other compiler directives in column 1 to highlight the fact
that they are not part of the logic flow of the program. They are processed before the program even starts.
Aligning them with the rest of the code would lead the reader to think that they are part of the logic flow.
Why do I suggest not using tabs? Different text editors handle them differently and/or allow different settings for
the number of spaces in a tab. Therefore, you don't have any
control over how the code will appear to other people if you use tabs. What looks aligned to you may very well
end up as a random mess in someone else's editor. Use spaces to indent.
Note that begin-select would never be found in column 1 under the
guidelines above. Many programmers assume that it must be there; in fact, only the names of the database columns
(fields) that you are selecting must be in column 1.
It's also common practice to use hyphens in procedure names but to use underscores or mixed case in variable
names. For example, we would have $variable_name
or $VariableName.
So here's an example showing these suggestions in practice:
!---------------------------------
begin-procedure Procedure-Name
!---------------------------------
begin-select
FIELD1
FIELD2
if &field1 = 'Y'
if #SomeVariable = 1
do Other-Proc-1
end-if
else
do Other-Proc-2
end-if
do Update-Table
FROM TABLE_NAME
WHERE FIELD2 = 123
end-select
end-procedure
!---------------------------------
begin-procedure Update-Table
!
! What this procedure does.
!---------------------------------
begin-sql
UPDATE ...
WHERE ...
end-sql
end-procedure
|
