July 6, 2004

SQR Code Formatting

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.

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

Until next time...