Sample COBOL coding standard

Sample COBOL coding standard 

This guide can be used in the development and maintenance of application systems written in COBOL for OS/390. It does not apply to code generated with an application code generator. This guide only refers to the COBOL for OS/390 programming language. 

This standard identifies the coding practices recommended for programmers to design, develop, and maintain COBOL for OS/390 programs, which are:

• Reliable
• Maintainable
• Structured
• Timely
• Efficient

The use of this standard will help the developers in the following ways:

• Reduce the time and effort required to develop programs.

• Provide developers the time to concentrate on the content of the program instead of the more mechanical aspects.

• Enhance the readability of programs.

• Provide continuity in program development and subsequent maintenance.
  
  
  
  
  These standards are subdivided into the following categories:

• General COBOL for OS/390 Programming practices
• COBOL for OS/390 Naming Conventions
• COBOL for OS/390 Coding Practices
• Efficiency Considerations

1.General COBOL for OS/390 Programming Practices

1. All new programs must be written in the latest available release of COBOL for OS/390.

2. All programs requiring maintenance should be converted to the latest release of COBOL for OS/390. The only exception will be for those instances where downward compatibility is required.

3. The COBOL standard is COBOL for OS/390.

2.COBOL for OS/390 Naming Conventions

This section contains global naming conventions for all COBOL for OS/390 applications.

2.1.Program Names

All programs and includes should begin with the two character application identifier. For example, all the programs within the CM application will be named CM******.

2.2.Generic Naming Conventions

All data, record, and file names should conform to the following structure:

A-XXX-YYY (or optionally) A-SS-XXX-YYY

Where:

A = One of the following

P = Print reports

O = Output data

S = Files destined for external sort

W = Working Storage members

I = Input data

SS = An application prefix

XXX = A meaningful abbreviation of the name

YYY = A suffix (if required)

Example:

I-INPUT-FILE

S-SORT-REC

P-PRINT-REPORT

WP-PARAMETERS

WA-ACCUMULATORS

WC-CONSTANTS

WF-FLAGS

WM-MESSAGES

WRn-REPORTLINE

WS-SWITCHES

WTn-TABLENAME

WTn-INX-TABLENAME

WTn-SUB-TABLENAME

WL-LINKAGE

WW-MISCELLANEOUS

2.3.File Section

Record layouts should not be defined in this section. All descriptions should be in Working-Storage. The only exception would be for high volume files.

2.4.File Names

See “Generic Naming Conventions” in topic 3.2.2 and add the suffix “-FILE”.

Example:

I-CONTROL-FILE.

2.5.Record Names

See “Generic Naming Conventions” in topic 3.2.2 and add the suffix “-REC”.

Example:

I-DEPARTMENT-REC PIC X(100)

2.6.Working Storage Section

There are two parts to a Working Storage item:

1. The prefix (i.e., WA), which identifies the structure.

2. The descriptive data name, which describes the data element.

Example:

01 WA-DEPT-TOTALS

05 WA-TOT-GROSS-SAL PIC S9(7)V99 COMP-3.

05 WA-TOT-TAX PIC S9(7)V99 COMP-3.

05 WA-TOT-NET-SAL PIC S9(7)V99 COMP-3.

2.7.Paragraph Names

All the paragraph names used in the Procedure Division must conform to the following conventions:

Entry Paragraphs: ANNN-XXXXX

Where:

A = 1 to 9 or A to Z (do not mix numeric with alpha values)

NNN = a sequence number (000 to 999)

XXXXX = a meaningful abbreviation for the purpose of the paragraph

Exit paragraphs: ANNN-EXIT

The ANNN part of the entry and exit paragraph names must be the same. In addition, the numbering scheme adheres to the following hierarchy:

• The main paragraph will be called 000-MAIN-PARA and paragraphs performed from here will be prefixed by “1000-”, “2000-”, “3000-”, etc.

• Paragraphs performed from 1000-INITIALIZATION will be prefixed by “1100-”, “1200-”, etc.

• Independent functions such as file reads, file writes, and abend routines will be prefixed by “9100-”, “9200-”, etc.

Example:

1000-INITIALIZATION.

PERFORM 9100-OPEN-FILES

....

....

1000-EXIT.

EXIT.

3.Coding Practices

This section discusses the coding rules to be followed for COBOL for OS/390 programs for each of the four divisions of a COBOL for OS/390 program. Be consistent with the use of literals, figurative constants, relational operators, etc.

3.1.Identification Division

1. The word IDENTIFICATION should not be abbreviated.

2. The following entry must be coded:

PROGRAM-ID. XXXXXXXX.

3. Comment lines must be added at the end of the division that provides a brief description of the purpose of the program and its function. A summary of the files, tables, and databases that are accessed, created, or updated by the program must also be contained in the comment lines. Follow this by a standard format of the program maintenance log, as defined by your application area.

3.2.Environment Division

1. Each SELECT statement must appear on a separate line.

2. The following clauses, if used, must each appear on a line by themselves and must be aligned to the ASSIGN clause:

ORGANIZATION

RECORD KEY

FILE STATUS

3.3.Data Division

See “Generic Naming Conventions” in topic 3.2.2 for data division information.

3.4.File Section

1. The order of appearance of the FD statements should be the same as the order of appearance of the SELECT statements.

2. For each FD statement, the 01 level entry must be preceded by a blank line.

3. In FD entries, clauses such as BLOCK CONTAINS and LABEL RECORDS must appear on separate lines.

4. The BLOCK CONTAINS clause should specify 0.

5. Do not use the RECORD CONTAINS N TO N CHARACTERS clause.

6. The LABEL RECORDS and RECORDING MODE clauses should be used only when necessary.

7. The DATA RECORDS clause is for documentary purposes only and should not be coded.

8. Do not use the SAME RECORD AREA clause.

3.5.Working Storage Section

1. The reserved word PICTURE should be abbreviated to PIC, begin all PIC clauses in the same column.

2. The REDEFINES and OCCURS clause must be coded in the next line after the data name and must be aligned with the data name.

3. The PIC clause must be followed by two (2) blanks for alpha or non-signed numeric strings. Signed numeric operators must have only one (1) blank preceding it.

4. The level numbers must be incremented in steps of 5 at all levels after the 05 level and must be indented by 4 columns on each increment.

Example:

01 I-TXN-REC

05 I-TXN-TYPEPIC X(2).

05 I TXN PAYMENT.

10 FILLER PIC X(2).

10 I-TXN-AMT PIC 9(5)V99 COMP-3.

10 I-TXN-AMT-R

REDEFINES I-TXN-AMT PIC X(7).

05 I-TXN-BALANCE PIC S9(7)V99 COMP-3.

05 I-TXN-HRS-WORKED

OCCURS 5 TIMES PIC S9(2) COMP.

5. Do not use 77 level data names.

5. A blank line must precede each 01 level data name.

5. Avoid the use of elementary 01 level data names.

5. All functionally or physically related data images must appear together defined within a 01 level description.

5. When coding literals in the VALUE clause, the trailing blanks can be ignored.

5. The optional reserved word USAGE should not be coded to enhance readability.

5. The use of 66 level data names is prohibited.

5. Tables with predefined values must be coded as follows:

01 WT1-TABLES.

05 WT1-TAB-DAY-OF-WEEK-R.

10 FILLER PIC X(10) VALUE ‘SUNDAY’.

10 FILLER PIC X(10) VALUE ‘MONDAY’.

...................................

05 WT1-TAB-DAY-OF-WEEK

REDEFINES WT1-TAB-DAY-OF-WEEK-R

OCCURS 7 TIMES PIC X(10).

13. Use one 01 level per line type of a report.

13. Packed decimal (COMP-3) variables should be described with an odd number of digits.

3.6.Procedure Division

1. Do not use sections.

2. A blank line must precede each paragraph name.

3. Only one COBOL for OS/390 statement is allowed per line.

4. If a statement is coded in more than one line, the second line must be indented by 4 columns and subsequent lines must be aligned to the second line.

Example:

READ I01-CONTROL-FILE INTO W05-CONTROL-FILE

AT END

PERFORM 9900-CLEAN-UP.

5. Use explicit terminators such as END-IF and END-READ when their use makes coding more understandable.

5. You must code the IF conditional expression clauses, such as ELSE, AT END, and INVALID, on a line by themselves.

5. The IF statement should be coded as follows:

IF WC-MS-BACHELOR

PERFORM 2230-CALC-HIGH-PREMIUM

ELSE

PERFORM 2240-CALC-LOW-PREMIUM

END-IF.

8. The destination of a GO TO statement must be an EXIT paragraph.

8. Do not use the ALTER statement.

8. Do not use commas and semicolons, as they do not have any syntactic function and obscure readability.

8. Avoid paragraphs that contain only a few lines unless paragraph is performed from multiple locations within the program

8. Structured periods may be used in conjunction with scope terminators, i.e., place the period on a separate line wherever required, but not necessarily after each COBOL for OS/390 statement.

8. Do not use in-line I/O statements. All I/O statements should be contained in separate paragraphs and these paragraphs should be performed.

8. The use of the MOVE CORRESPONDING option should be limited to data and time format conversions.

8. Parentheses should be used to make IF and COMPUTE statements explicit and readable.

8. Avoid using the GO TO...DEPENDING statement.

8. Use the ‘/’ command to ensure each paragraph starts on a new page on the compiler listing unless the paragraphs are extremely short.

8. Use only one GOBACK statement in the program.

8. Use only one READ/WRITE paragraph per file.

8. Use a separate INITIALIZATION-ROUTINE to initialize data, open files, read first record and perform other operations required prior to processing the data.

8. Use READ INTO and WRITE FROM for low volume files. For high volume files, use READ and WRITE without INTO or FROM, respectively.

8. Use libraries wherever possible, e.g., common routines, record layouts, etc.

8. Avoid the use of ‘NOT’ logic for nested IFs.

8. Use CONTINUE rather than NEXT SENTENCE unless you want to skip the execution of subsequent statements.

8. Display any input parameters before starting the processing.

8. Place comments in front of all major paragraphs. In case of comments placed in between lines of code, clearly identify them by putting asterisks (*) in columns 7 through 10.

8. Delete all unexecutable code, including code, which has been commented out, when appropriate.

8. Use the PERFORM verb with the UNTIL clause to establish and control loop logic.

8. Fall-throughs of paragraphs are not allowed.

8. IMS BMP programs that update databases must be coded with checkpoints.

8. Programs that exercise DL1 functions must be coded to test for valid return status values from the requested action. This is also true for DB2 functions.

4.Efficiency Considerations

Next to good structure, good performance is the most desirable quality in a program. Good performance is a measure of one or more of the following attributes:

• Efficiency
• Throughput
• Response time

However, it is not desirable to sacrifice program structure for performance. Programmers should use good judgment in deciding when to use the recommendations in COBOL for OS/390 Optimization Techniques.