Clear COBOL in Easy Steps

Clear COBOL in Easy Steps

David Greer, March 1982, SMUG II

The following rules for the coding of COBOL programs may seem restrictive to some, but in the long run they will make your programs clearer and more reliable because they force you to think clearly about what you are writing. These rules assume that the PROCEDURE DIVISION will be broken into many SECTIONs, where a SECTION is about one page (i.e., about 60 lines) of COBOL code. Each SECTION name starts with a unique number and the end of SECTION is a single paragraph containing an EXIT statement. SECTIONs are decomposed into paragraphs and programs are decomposed into SECTIONs.

GOTOs are not allowed, except to transfer to the exit of the SECTION that you are currently in. The GOTO exit must be in the mainline part of the SECTION and not in one of the paragraphs within the SECTION.
Always PERFORM things below you. If you are in SECTION 10, you cannot PERFORM SECTION 05. Instead, rename SECTION 05 as SECTION 15, move the code, then PERFORM it. In this way, when you are reading a program, you always read forward and you never need to look back.
Always PERFORM a SECTION THRU. This guarantees that the SECTION will remain as a small su-part of the whole program, and that it will never be possible to accidentally "fall through" the code into the following SECTIONs.
Each SECTION starts with a header comment. This comment should not just repeat the code in the SECTION; it should explain what the SECTION is attempting to do in terms of the global context, and especially in terms of any flags that are set or buffers that are filled. Remember that this is the reader's second line of defense in trying to understand your code, so it shouldn't just echo the obvious parts of the code.
SECTIONs should never exceed 1-1/2 to 2 pages. This rule can be relaxed if there are many simple database calls, as there are when you initialize database field lists. If you find that a complicated SECTION is becoming more than a page and a half, reexamine what it is supposed to do and rewrite it as two SECTIONs.
SECTIONs should have a small control area at the start, following by a GOTO exit. This control area normally consists of PERFORMs of other SECTIONs and paragraphs, as well as IF statements to control the flow of execution. This is NOT the only thing that the control area can contain, but these are the most common elements.
Only PERFORM paragraphs within the current SECTION. The only exceptions are small utility paragraphs declared in a special SECTION. This SECTION has no control at the start; instead it consists of paragraphs with some logical element in common (e.g., standard database calling paragraphs).
Use logical flags for program flow. For example, the following segment might be used to input a valid customer number:
```
   01  CUSTOMER-FOUND-FLAG        PIC X.
       88  CUSTOMER-FOUND         VALUE "T".

   MOVE FALSE TO CUSTOMER-FOUND-FLAG.

   PERFORM 20-ACCEPT-CUSTOMER-FLAG
      THRU 20-ACCEPT-CUSTOMER-CODE-EXIT
     UNTIL CUSTOMER-FOUND.
```
The ACCEPT-CUSTOMER-CODE SECTION is responsible for setting CUSTOMER-FOUND-FLAG when a correct customer is entered. This makes the program logic flow clear to the reader. Just by reading the PERFORM statement, the reader is aware that the ACCEPT-CUSTOMER-CODE SECTION may be repeated.
If a program will be larger than 2500 lines of COBOL source code, it should be broken into subprograms. The design of subprograms must be done when the program is designed, instead of after the program is implemented. Remember that subprograms can be used to make a program more manageable, easier to understand, and less of a drain on system resources.
Avoid NEXT SENTENCE, as this usually obscures the object of an IF expression. There are certain cases where a NEXT SENTENCE is not needed at all. For example,
```
    IF DB-STAT-OK THEN
       NEXT SENTENCE
    ELSE
       DISPLAY "NO SUCH CUSTOMER".
```
should be written as
```
    IF NOT DB-STAT-OK THEN
       DISPLAY "NO SUCH CUSTOMER".
```
This makes the code simpler to read and to understand. When an IF expression becomes too complicated, use extra paragraphs instead of NEXT SENTENCE to clarify the intent of the expression. Note that the use of NEXT SENTENCE must be balanced against a desire to have IF expressions use the positive. Where possible avoid the NOT construct. Instead, use extra paragraphs to make the program logic more readable and easier to maintain.
Write and test a large program in small pieces. Each new 200-300 lines of code should be compiled and debugged before writing more code. While this extra time often seems wasted, it almost always results in a program with fewer bugs. It is easier to debug 200 lines of new code than it is to debug 2000 lines.
Never use VALUE clauses on variables except when they are constants or 88-levels (that is, variables that never change their value during execution). All other variables should be initialized, as needed, by statements in the PROCEDURE DIVISION.
Every program has one normal termination point. The program is terminated by a GOBACK and never by a STOP RUN. If there is an error exit, it must be localized to one SECTION, and the error exit must terminal the program (by calling Quit on MPE).

David Greer