Data Names in COBOL

Data Names

As with paragraph names, it pays to choose your data names carefully.

Someone reading the PROCEDURE DIVISION will assume that a variable means just what its name suggests. If the name suggests nothing, the reader will have to either guess or spend a lot of time on a tedious investigation. If the name seems meaningful but is in fact misleading, the consequences are even worse.

Use Meaningful Names

This advice is so obvious that no one should have to mention it, yet not everyone follows it.

There are several reasons why people use meaningless or cryptic names:

Conformance with the cryptic names demanded by Assembler or primitive dialects of Fortran.
This reason is somewhat defensible. For example, a code generator may translate a record layout from Assembler to COBOL. Using the resulting gibberish as a copybook may make maintenance more manageable in a multi-language application.

A desire to avoid long names in order to reduce typing.
In practice, typing time is a small fraction of a programmer's workday. At best, short names don't save much. At worst, they are a false economy, because they may force us to spend more time figuring out how the code works.

A desire to avoid long names in order to fit more on a line.
Rarely is there any reason to fit more than two data names on the same line (main exception: when one of them is subscripted). Unless your code is deeply indented, probably because of excessive nesting, there's almost always enough room.
For the occasional exception, it's no big deal to continue a statement on the next line.

Excessive faith in the clarity of abbreviations.
Six months after you write the program, it may be difficult to remember that PCS meant "previous class of service".

Apathy? Whimsy? Who knows?
One general ledger program used to contain a variable named, for no discernable reason, "BEANO". Go figure.
(It is probably no coincidence that the same program was a ghastly mess in many respects, and quietly corrupted the books for years before a subtle bug was found amid the spaghetti code.)

Avoid Potential Reserved Words

COBOL II has almost 600 reserved words, most of them obscure. Other dialects have their own variations. If you try to use a reserved word as a data name, the compiler will complain.

What if you switch compilers? Or upgrade to a new release? There may be a different collection of reserved words, colliding with one of your data names.

You can't predict what will become a reserved word, but you can avoid possible candidates. For example, I would never name a variable SELECTION. It's just a little too close to SELECT (an SQL operator, and a reserved word in COBOL II).

One simple rule is to include a hyphen in every data name. Few reserved words include hyphens, and WS-SELECTION is unlikely ever to become a reserved word.

Use Prefixes to Associate Related Items

This guideline applies especially to record descriptions. Typically everything in the same copybook should have a common prefix in the name: JKU-RECTYPE, JKU-WTN, JKU-CLS-SVC, and so forth.

Items in WORKING-STORAGE can benefit from the same treatment. For example, you might have a table, each element of which has ten subfields. Apply a distinctive prefix to each name in the table: TAB-WTN, TAB-USOC, and so forth.

I often use a prefix of LINK- for items in the LINKAGE SECTION, unless they are in copybooks.

Use Suffixes to Designate Special Data Types

For indices, add "-X", as in WTN-X or USOC-X. For numeric items used as subscripts, add "-SUB", as in WTN-SUB. For pointer variables, use "-P", as in FIRST-WTN-P.

Other, more specialized suffixes may be useful in a particular context.

Spelling Counts

It's hard enough to remember a name like WS-CALENDAR-TABLE. It's even harder to remember to misspell it as WS-CALENDER-TABLE.

Don't even use a word which is commonly misspelled, like calendar, receive, or occasion. Or misspell.

Use Common Opposites

Suppose you need to store a WTN range as a first number and a last number. You can call them FIRST-WTN and LAST-WTN, or you can call them BEGIN-WTN and END-WTN. Don't choose an unnatural combination like FIRST-WTN and END-WTN.

Other common pairs of opposites include min/max, start/stop, old/new, and next/previous.

Avoid Names that Look Alike

Any two data names in the same program should differ by more than one or two characters. Otherwise they will be too easily confused.

(Main exception: names that differ only in their prefixes, such as JKR-CUST-CODE and JKO-CUST-CODE. We can expect the reader to pay attention to prefixes, whose sole purpose is to distinguish among similar variables.)

Be especially wary of characters that look alike:

The letter G and the numeral 6;

The letter I and the numeral 1;

The letter O and the numeral 0;

The letter S and the numeral 5;

The letter Z and the numeral 2.

You can avoid all the above pairs by following a simpler rule: don't put digits in your data names.

Avoid data names with similar meanings. For example, don't have both REC-NUM and NUM-REC. It's too hard to remember which is which.

Use Abbreviations Carefully

Abbreviations are a two-edged sword. They can contribute to readability by reducing the sheer verbiage in a language famous for its verbosity. They can also obscure.

Don't hesitate to use abbreviations sanctioned by long usage: EOF for End Of File, SSN for Social Security Number, or whatever is common within your industry or your application. Anyone reading your program should be expected to recognize them.

Where there is no standard and familiar abbreviation, be reluctant to invent your own, especially if the abbreviation would appear in only a few places.

Don't abbreviate just to save one or two keystrokes. ORDER-FL is only a little shorter than ORDER-FILE, but it is significantly more obscure -- and sooner or later somebody will get a compile error because he forgot to abbreviate.

When you do abbreviate, be consistent, both within a program and across the application. Don't force someone to try to remember whether a variable is WS-CLASS-OF-SERVICE, WS-CLS-SVC, WS-CLS-SERV, or WS-COS.

Avoid abbreviations that might be misunderstood. For example, don't use REC to mean "receive". Instead, use RECV, so that it won't be confused with "record".

When possible, use abbreviations which you can pronounce. For example, use CURR-DATE instead of CRNT-DTE. It's easier to read and easier to discuss over the phone.

When Short and Even Cryptic Names May Be Okay

One hesitates to approve a truly cryptic name. Still, the following circumstances may mitigate the crime:

The variable is an index or subscript, with an appropriate suffix as described above.

The entire program is short and simple (perhaps it is a subprogram).

The variable appears only in a single paragraph, preferably a short one, or in two closely related paragraphs.

The variable is used all over the place, so that anyone reading the program must quickly become familiar with it anyway.

The meaning of the variable is documented by an appropriately placed comment.

The meaning of the variable is so convoluted that you can't express it clearly within 30 characters. It's hard to come up with a plausible example, but in theory it could happen.

Naming Flags and Switches

In most cases it doesn't matter what you name them. Whenever possible, access flags and switches exclusively through 88-level variables. The variable itself doesn't even need a name -- you can hang 88-levels off of FILLER.

For a simple binary switch, the 88-levels should have identical names, except that one of them should contain 'NOT' somewhere.

For a flag with more than two possible values, give the 88-level names a common prefix -- long enough to make them highly distinctive.

COBOL Home

COBOL Style Forum