Paragraph Names

Choose your paragraph names carefully. While a well-chosen name will earn you no medals, an ill-chosen one may earn you a thousand curses.

Suppose you see some code which performs 2840-READ-INPUT-REC. Are you likely to wonder what that paragraph does? No, you'll just assume, without looking further, that it's about three lines long. It'll READ something, check for end-of-file, and maybe increment a counter.

If you're right, fine. But suppose that 2840-READ-INPUT-REC doesn't just read a record. It also writes an output record, updates a database, and issues a formfeed on a report. How many hours will you waste before you figure out what's going on? Believe it or not, preposterous programs like this really exist.

Objectives of a Good Name

A good paragraph name meets two objectives:
  1. It accurately describes what the paragraph does;

  2. It suggests where the paragraph fits in the program structure.
By convention, paragraph names have two parts. One part consists of text which describes what the paragraph does. The other part is a prefix which uses some kind of numbering scheme to indicate structural information.

In JOCKEY the prefix is a four-digit number followed by a hyphen (or three digits in some small programs). This convention is common, though some shops use alphabetic or alphanumeric prefixes.

Describing What the Paragraph Does

The text portion of a paragraph name should contain two or three words:
  1. A verb, in the imperative mode;

  2. An adjective (optional);

  3. A noun, serving as the object of the verb.
With minor exceptions, in a well-structured program you can devise such a name for every paragraph. Each name should correspond exactly to what the paragraph does, with nothing left out or left over.

If you can't come up with an accurate name without using the word 'and,' then reconsider your design. Your paragraph is probably jumbling things together that don't belong together. If not, try looking at your paragraph from a higher level of abstraction. For example, READ-AND-VALIDATE-RECORD might become GET-VALID-RECORD.

Be as specific as you can. Wimpy words like 'process' or 'handle' drain a name of its meaning.

(By tradition, the uppermost paragraphs are exempt from this rule. No one will be baffled by a conventional PERFORM 2000-PROCESS-RECORD, even if it is a bit vague.)

Even if the paragraph is PERFORMed with an UNTIL clause, the name should tell what the paragraph does on a single invocation. For example: you are loading a WORKING-STORAGE table from a file, PERFORMing a paragraph for each record. The name of that paragraph should be 1310-LOAD-RECORD, not 1310-LOAD-TABLE.

Numbering Schemes

JOCKEY mostly follows the following conventions in numbering paragraphs:
  1. Paragraphs are physically in numerical order. If you move them around, renumber them accordingly.

    We can afford to make this rule absolute, since it is easy to follow. An occasional global edit is a small price to pay for being able to find paragraphs easily.

  2. The number of trailing zeros is a rough indicator of the hierarchical level.

    The topmost paragraph is numbered 0000. It typically performs 1000, 2000, and 3000. The next level down would have numbers like 1100, 2700, and so on. Only the lowest-level paragraphs have no trailing zeros at all.

    In a strict application of this rule, there could only be five levels. Since that's usually not enough levels in a non-trivial program, we bend the rule as convenient.

  3. For the most part, each paragraph performs paragraphs with similar leading digits. Paragraph 2000 performs paragraphs starting with 2. Paragraph 2600 performs paragraphs starting with 26.

    This rule tends to bring related paragraphs together, especially at lower levels. Paragraphs mostly perform paragraphs which follow them in the source code. Not only does this pattern make the code more intuitive to follow, but it may also reduce the number of page faults at run time.

An Alternative Style

Some people prefer to prefix paragraph names by function, in addition to a paragraph number. For example, the name of an input routine might start with 'I'; the name of an output routine would start with 'O'. We can add a special tag -- such as a leading 'U' -- for so-called 'utility' paragraphs: namely, any paragraph performed by more than one other paragraph. These specially tagged paragraphs are typically grouped together at the end of the source file.

Any convention sanctioned by common usage deserves some respect. Still, this style has little to recommend it.

The text portion of a paragraph name can (and should) indicate what a paragraph does. To encode a crude functional category in the prefix adds nothing.

More importantly, it is a bad idea to group these specially tagged paragraphs at the end of the source file, remote from the code which invokes them. Programs are easier to read and maintain when closely related code is grouped together.

On the other hand, some paragraphs (such as 9999-ABEND) are invoked in numerous places. It makes sense to put them toward the end of the source code, but there is little point in creating an extra numbering scheme for them.

Afterword

Colin Campbell has reminded me that all of the above applies equally to section names. However, if you follow the advice I give elsewhere, you will seldom or never use sections anyway.
homeCOBOL Home [style forum]COBOL Style Forum