NOTE: THESE STANDARDS WERE WRITTEN FOR COBOL 68 / 74.
THERE MAY BE SOME DIFFERENCES FOR COBOL 85.
INTRODUCTION
Standardization has numerous benefits, among those being the increased
productivity and ease of maintenance which result from improved documentation
and better program structure.
The intent of this document is to provide some rudimentary design and
programming guidelines. It is not by any means intended to be exhaustive
in it's scope, nor represent the final word in programming style.
Comments and suggestions are encouraged.
SECTION I: COBOL CODING CONVENTIONS:
A. DATA DIVISION.
1. Use descriptive names for variables, files and procedures. COBOL
permits user defined names up to 30 characters in length. Use
names which provide clarity.
2. Align all the clauses in the data descriptions, i.e., level
numbers, pictures, values and usage should all begin in the same
column. Exceptionally long literals should be placed on a
separate line by themselves.
3. Subordinate level numbers should be indented 4 character positions
to clearly show the hierarchy of the data description.
4. When defining a table/array, a numeric data item should also be
defined and initialized to a value that equals the occurrences
of the table. The data item can then be referenced in the
procedure division, in lieu of a numeric literal, when a value
must be checked against the size of the table.
5. Cobol data names can be up to 30 characters. File names and
DMSII data names should be 17 characters or less.
B. PROCEDURE DIVISION:
1. The perform statement is the only permissible way to execute code
segments. The "UNTIL" phrase of the perform statement is used to
control iteration, or looping, until a specific condition is
satisfied.
2. The use of "GO TOs" should be restricted to referencing a paragraph
name forward of the GO TO statement within the same procedure being
performed. For instance, a series of conditionals within a procedure
which is executed via a "PERFORM PARA-NAME THRU PARA-EXIT", may be
exited via a "GO TO" PARA-EXIT if an earlier conditional precludes
the necessity of applying the remaining conditional tests. GO TO
statements branching to the exit paragraph of the performed section
may be used to break up excessively complex IF-ELSE structures.
The "GO TO DEPENDING ON" clause should only be used if not using
it would otherwise result in excessively complex and difficult to
understand coding. No other use of the GO TO statement is
permitted.
3. Some COBOL constructs such as "RENAMES", "EXIT HERE" and "ALTER"
should never be used.
4. There is always an implicit none-of-the-above category that
drops through a series of conditional tests to the statements
following the tests. A series of conditionals should include
a "none-of-the-above" category to provide a small measure of
protection against unexpected values.
5. The use of numeric and alphanumeric constants within the procedure
division should be avoided. Instead use descriptive variables
initialized to a constant value.
6. The use of program switches of the form "PGM-SW-A = 1" or
"PGM-SW-A = 0" is not permitted. Switches of this form do not
clearly communicate their intent to anyone other than the
original programmer for several reasons: switch names tend to be
too cryptic to be easily understood by anyone other than the
original programmer, and the values "1" and "0" often times are
not used consistently to indicate an "on" or "off", "yes" or
"no" condition. Code two working storage items, "YES" and "NOPE"
with initial values of "1" and "0". Create switches named in such
a manner that their comparison to "YES" and "NOPE" will answer the
question, "What condition must occur for this code segment to be
executed?". (for example "IF FIRST-RCD-READ = YES") The
prefered method of handling this is to code 88 level condition
name entries associated with the switch. The switch asks the
question, WAS-FIRST-RCD-READ?, the value moved to the switch
answers the question and is a value associated with one of
several possible condition names such as, THIS-IS-FIRST-RCD or
FIRST-RCD-WAS-READ.
7. Multiple open and close filename statements should not be buried
or hidden throughout the program. When possible they should occur
in the main paragraph, an initialization procedure secondly or, if
unavoidable, the beginning of a major code segment.
8. Code only one statement per line.
9. A numeric prefix should be appended to the beginning of every
section and paragraph name. The assignment of the prefix should
be in an ascending sequence to allow for a quick location of any
section or paragraph.
10. Use blank lines to separate groups of code within a paragraph
or section for easier readability. Use page breaks to separate
paragraphs and/or sections.
C. GENERAL
Document while the code is being written. The original programmer is
most deeply involved in the decisions which determine how the module
is programmed and is best able to comment on the rational behind each
code segment, the purpose of a conditional test or why a particular
structure or technique was used. If documentation is left to the end
of the project the temptation is to move on to the next project before
going back to fully document the one just completed.
Readability should always be a primary coding consideration.
Programming standards developed for use by all employees of the
UW Information Systems staff have been documented in the UW ADP
Policy, Standards, and Procedures manual, Volume 2, Part 3, Section 3.
All programs must be structured. They should be designed and coded
using accepted top down logic, ie, paragraphs or sections performing
general tasks should in turn perform paragraphs or sections performing
specific tasks, etc.
SECTION II: MODULAR DESIGN AND PROGRAMMING.
The goal of modular design and programming is to eliminate omissions,
misunderstandings and unstated assumptions during the design and programm-
ing stages. Good documentation is an integral part and result of modular
design and programming. Good documentation facilitates peer review and
illustrates adherence to design concepts and system standards in addition
to providing clear checkpoints for control over progress.
A. MODULARITY - THE TOP DOWN APPROACH
There are several approaches to modular design and programming; of
those that address portability and ease of maintenance, the two most
common are based on processing flow within the program (the main-flow
method) and the idea of levels of abstraction or decompositions (the
hierarchical approach).
1. The main-flow method more closely resembles conventional flow-
charting techniques. Design decisions are based upon isolating
program functions within specific procedures earlier in the design
process. Specifications more closely mirror the processing flow
within the program.
2. Using the hierarchical method a process is analyzed at the
highest level of abstraction and solved in terms of functions
appropriate at that level. The process is then decomposed
to successively lower levels with each level more detailed than
the last. As little as possible is assumed at each step in the
design process. The assumptions are refined with each succeeding
step.
3. A combination of the flow method and hierarchial method provides
the greatest measure of clarity and specificity. The function of
each segment and the interrelationship between segments should be
fully clarified.
a. The first or main section of the procedure division should
provide a table of contents for the program.
b. A related set of procedures that are necessary to perform a
single function should be placed in their own code segment.
c. Code segments should begin at the top of a page in the
listing.
d. There should be a single entry point and exit point from
each segment.
B. MODULARITY AND THE SKELETON PROGRAM APPROACH TO PROJECT IMPLEMENTATION
The skeleton approach illustrates and enforces standards, helps provide
uniformity throughout a system, control over development progress and
increased productivity and efficiency. There is a presupposition as
to the correctness, applicability and quality of the skeleton and
related library code. If this is not assured the results are poorly
defined inter-module interfaces, difficulty of maintenance, and loss
of reliability due to the replication of poorly designed code through-
out the system.
1. First Stage:
Encode and library file and record descriptions used in the
programs or modules.
2. Second Stage:
Create the skeleton module. Augment the procedure division
with a standard structure that performs the major procedures.
This will insure that all the program/modules perform specific
functions at predictable paragraphs. Compile the skeleton.
3. Third Stage:
Create libraried code segments that can be utilized by all
program/modules. Recompile the skeleton with the libraried
code segments and test.
4. Fourth Stage:
Clone the skeleton as many times as is needed.
5. Fifth Stage:
Review program specifications for applicability against the
program/module to be customized.
6. Sixth Stage:
Program customization and completion using program specifications.
SECTION III: MIGRATION TO OTHER ANSI COBOL STANDARDS.
The diversity of hardware architectures necessitates programming as much as
possible for maximum portability. Some of the obstacles to program
portability will be eliminated with the migration from COBOL-68 to
either COBOL-74 or COBOL-85.
All new development should be written with ease of migration in mind,
meaning the elimination of vendor supplied COBOL extensions and the
resolution of COBOL language differences.
A. NON-SUPPORTED COBOL EXTENSIONS
The Burroughs COBOL extensions frequently used in this shop which can
no longer be used are:
1. "On Exception ... else", "At End ... else" or "Invalid Key ... else".
2. The logical connectors (and, or) can no longer be omitted from a
list of objects to a relation condition, i.e. If A = 1, 2, 3 or 4
should be stated, If A = 1 or 2 or 3 or 4.
3. The SIZE clause cannot be used as a substitute for PIC.
4. The "Exit Here" clause will no longer be permitted.
B. LANGUAGE DIFFERENCES (COBOL-68/COBOL-74).
1. The abbreviation of the "VALUE" clause to "VA" is not permitted
in COBOL-74.
2. BLOCK CONTAINS and RECORD CONTAINS clauses must be stated in
characters, not words.
3. COMP must be used instead of COMP-2 in the DATA-DIVISION.
BINARY instead of COMP or COMP-1.
4. Numeric and numeric-edited data items are not allowed to
exceed 23 bytes in length.
5. All data items should be byte aligned.
6. Copy libraries must be referenced using the "COPY" statement;
"$SET FROM" AND "$FROM" are not allowed in COBOL-74.
7. Moving "ZEROES" to a comp. item will result in Display ZEROES
(HEX F0) being moved. Low values should be used instead of ZEROES.
B. OTHER LANGUAGE DIFFERENCES (COBOL-68/COBOL-74).
7. The "OCCURS" clause is not allowed at the 01 level in COBOL-74.
8. "MOVE CORR" can have only one receiving field.
9. "EXAMINE" statements should be changed to "INSPECT".
10. Any references to "CHANNEL 1" in write statements should be
changed to "PAGE".
11. "CLOSE WITH LOCK" will need to be changed to "CLOSE WITH SAVE".
12. Computations involving dates and times are different in COBOL-74.
See pages 16 and 17 of Larry's COBOL-74 Implementation and
Conversion document for more detail.
