COBOL Documentation

Documenting COBOL programs helps future maintainers (and yourself) understand what a program does, when it was written, and how it is structured. The IDENTIFICATION DIVISION holds the program name (PROGRAM-ID) and optional documentation paragraphs such as AUTHOR, DATE-WRITTEN, and REMARKS. Comments in the source code use an asterisk in column 7 for a full line or, in COBOL 2002 and later, >* for inline comments. This page explains how to document COBOL programs and what each option means.

Explain Like I'm Five: What Is Program Documentation?

Documentation is like labels on a box: who made it, when, and what is inside. In a program, the IDENTIFICATION DIVISION is the label that says what the program is called and (optionally) who wrote it and when. Comments in the code are like sticky notes next to tricky parts: they explain what a section does without changing how the program runs. Good documentation makes it easier for someone else (or you later) to fix or change the program without guessing.

Why Document COBOL Programs?

COBOL applications often run for decades and are maintained by many people over time. Without documentation, it is hard to know the program's purpose, what external files or programs it uses, or why a particular logic was chosen. The IDENTIFICATION DIVISION and comments do not change the compiled code but they make the source easier to read and maintain. PROGRAM-ID is also required so the system and other programs can identify and call this program. Taking a little time to add clear PROGRAM-ID, REMARKS, and comments pays off when someone has to fix a bug or add a feature later.

The IDENTIFICATION DIVISION

The IDENTIFICATION DIVISION is the first division in a COBOL program. It must appear before the ENVIRONMENT, DATA, and PROCEDURE DIVISIONS. The only paragraph that is required is PROGRAM-ID, which gives the program name. The name is used when the program is called (CALL, CICS LINK, etc.) and for listing and debugging; on many systems the first 8 characters must be unique and the first character must be alphabetic. Other paragraphs—AUTHOR, INSTALLATION, DATE-WRITTEN, DATE-COMPILED, SECURITY, and REMARKS—are optional and used only for documentation. In the ANSI 1985 standard and later, these optional paragraphs were classified as obsolete, and they are excluded from the X/Open COBOL definitions. However, most mainframe and other COBOL compilers still accept them, so they remain in common use for documentation.

PROGRAM-ID

PROGRAM-ID is the one required paragraph. You code it as PROGRAM-ID. program-name. The program name must follow the rules of COBOL user-defined words (typically alphabetic first character, then alphanumeric). On z/OS and many other systems, only the first 8 characters are significant for external identification, so keep names within 8 characters if you need to match system or CICS definitions. Some compilers allow additional attributes after the name (e.g. COMMON, INITIAL) for program behavior. Example:

1
2
3
4
5
6
7
       IDENTIFICATION DIVISION.
       PROGRAM-ID. ACCTUPDT.
       AUTHOR. MAINTENANCE-TEAM.
       DATE-WRITTEN. 2020-01-15.
       REMARKS.
           Updates customer account file from transaction input.
           Called by CICS transaction ACUP.

AUTHOR, INSTALLATION, DATE-WRITTEN, DATE-COMPILED, SECURITY

These paragraphs are optional and documentation-only. AUTHOR typically holds the programmer or team name. INSTALLATION holds the organization or site name. DATE-WRITTEN is when the program was written (often maintained manually). DATE-COMPILED is often automatically filled by the compiler with the compilation date when you compile. SECURITY is used to record a security or confidentiality classification (e.g. proprietary, internal). None of these affect compilation or execution; they are there so that anyone reading the listing or source can see who wrote the program, when, and for which installation. Because they are obsolete in the standard, avoid them in strictly conforming or X/Open programs; for most mainframe and legacy COBOL, they are still useful and widely used.

REMARKS

The REMARKS paragraph is free-form. It can span multiple lines and usually describes the program's purpose, main logic, files and programs it uses, and any important change history or dependencies. There is no fixed format; write whatever helps the next maintainer. Some teams use a standard template (e.g. Purpose, Files, Called programs, Change log). REMARKS is a good place to document why a program exists and how it fits into the application, not just what each line does (that is better in comments next to the code).

Comments in the Source

Comments are lines or parts of lines that the compiler ignores. They are for humans. In traditional COBOL, you put an asterisk (*) in column 7 (the indicator area). The entire line is then a comment. Column 7 is in the so-called Area A in fixed-format COBOL; the exact column can vary by compiler and format (fixed vs free), but the idea is the same: a special character in the indicator area marks the line as a comment. Do not put executable code on the same line after the comment; the whole line is commentary. Use comment lines for section headers (e.g. *--- OPEN FILES ---) and for blocks of explanation above a paragraph or section.

In COBOL 2002 and later, the floating comment indicator >* (asterisk followed by greater-than) starts an inline comment. From >* to the end of the line is a comment. That lets you add a short note on the same line as a statement. Not all compilers support >*; check your compiler documentation. If you use free-format COBOL, comment rules may differ slightly (e.g. * in column 1 or >* anywhere).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
*==============================================================
*  OPEN FILES AND READ FIRST RECORD
*==============================================================
       OPEN INPUT ACCT-FILE.
       IF WS-STATUS NOT = '00'
           PERFORM ABEND-ROUTINE
       END-IF.
       READ ACCT-FILE
           AT END SET WS-EOF TO TRUE
       END-READ.
*> Check for valid key range before update
       IF WS-ACCT-KEY >= WS-MIN-KEY AND WS-ACCT-KEY <= WS-MAX-KEY
           PERFORM UPDATE-RECORD
       END-IF.

What to Document

• Program purpose: what the program does and why it exists (REMARKS or top comment block).
• Files: which files are read or written and their record layout or key if not obvious.
• Called programs: which programs are called (CALL, LINK) and what is passed.
• Complex logic: why a condition or formula is used, not just what the code does.
• Change history: if your shop keeps it in REMARKS or a comment block, note major changes and dates.
• Restrictions or assumptions: e.g. "Input file must be sorted by key," "Valid only for type A records."

Step-by-Step: Adding Documentation to a Program

1. Ensure the IDENTIFICATION DIVISION has PROGRAM-ID with a clear, unique program name (first 8 characters count on many systems).
2. Add or update REMARKS (or AUTHOR, DATE-WRITTEN if your shop uses them) with program purpose, main inputs/outputs, and called programs.
3. At the top of the PROCEDURE DIVISION or at major sections, add a short comment block (lines with * in column 7) describing what the section does.
4. Next to complex or non-obvious logic, add a brief comment or >* inline comment explaining why, not just what.
5. When you change the program, update REMARKS or the change log if your standards require it.

Best Practices

• Keep PROGRAM-ID within 8 characters if your environment requires it for external references.
• Use REMARKS for high-level description; use comments near the code for low-level explanation.
• Avoid commenting the obvious (e.g. "Move A to B"); comment the non-obvious (e.g. "Use prior day balance because posting runs at midnight").
• Use a consistent style for comment blocks (e.g. *--- section name ---) so sections are easy to find.
• If you use DATE-WRITTEN or DATE-COMPILED, update or let the compiler update them so they stay meaningful.

Test Your Knowledge