COBOL Program Documentation

Program documentation is the practice of describing what a COBOL program does, how it is structured, and how to maintain it. It includes comments and REMARKS in the source code, naming and layout conventions, and often external documents such as program specifications. This page focuses on documentation standards, what to document, and how to write documentation that stays useful as the program changes.

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

Imagine a box of toys with no labels. You have to open every box to see what is inside. Program documentation is like putting labels on the boxes: "This program updates customer balances," "This section opens the files," "This paragraph runs when the input is invalid." When someone else (or you later) needs to change the program, the labels help them find the right place and understand what to change without guessing.

Why Document COBOL Programs?

COBOL applications often run for years or decades. Many people will change the code over time. Without documentation, it is hard to know why a program exists, what files and other programs it uses, or why a particular condition or formula was chosen. Good documentation:

• Speeds up maintenance and debugging by making intent and structure clear
• Helps new team members understand the system without reading every line
• Supports audits and compliance by explaining what the program does
• Reduces the risk of breaking behavior when making changes

Documentation does not change how the program runs; the compiler ignores comments and REMARKS. It only helps humans work with the code.

What to Document

Focus documentation on information that is not obvious from the code itself.

Documentation in the Source Code

The IDENTIFICATION DIVISION holds the program name (PROGRAM-ID) and optional paragraphs such as AUTHOR, DATE-WRITTEN, and REMARKS. REMARKS is free-form: you can describe purpose, files, called programs, and a short change history. Use it for high-level description that applies to the whole program.

Comments are for section-level or line-level explanation. In fixed-format COBOL, put an asterisk (*) in column 7 to make the entire line a comment. Use these for section headers (e.g. *--- OPEN FILES ---) and blocks of explanation. In COBOL 2002 and later, >* starts an inline comment from that point to the end of the line, useful for short notes next to a statement.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
       IDENTIFICATION DIVISION.
       PROGRAM-ID. BALUPDT.
       REMARKS.
           Updates customer balance from transaction file.
           Input:  TRANSFILE (key: CUST-ID), sequential
           Output: MASTFILE (key: CUST-ID), indexed
           Called by: BATCH-BAL (passes control)
           Change: 2024-01-15 - add support for type B transactions
       
       *==============================================================
       *  OPEN FILES AND READ FIRST RECORD
       *==============================================================
       OPEN INPUT TRANSFILE
                 I-O    MASTFILE.
       READ TRANSFILE AT END SET WS-TRANS-EOF TO TRUE END-READ.
       *> Use prior-day balance when posting runs after midnight
       IF WS-POST-TIME < WS-MIDNIGHT
           MOVE WS-PRIOR-BAL TO WS-WORK-BAL
       END-IF.

Documentation Standards

Many shops define documentation standards so that every program is documented in a consistent way. Standards may require:

• A clear PROGRAM-ID and a REMARKS block (or equivalent) with purpose, files, and called programs
• Comment blocks before each major section (e.g. file open, main loop, error handling)
• Naming conventions (e.g. WS- for working storage, verb-noun for paragraphs)
• No unexplained GO TO or obscure logic; complex conditions explained in comments
• A change log in REMARKS or a standard comment block when the program is modified

If your team has a standard, follow it. If not, adopting a simple set of rules (e.g. always REMARKS + section comments + meaningful names) still improves maintainability.

Naming Conventions for Readability

Consistent naming makes the code self-explanatory and reduces the need for extra comments. Common conventions include:

Paragraph names that describe the action (e.g. VALIDATE-INPUT, WRITE-OUTPUT-RECORD) act as a form of documentation. Avoid vague names like PARA-1 or PROCESS.

Program Specifications

A program specification (or "program spec") is a description of the program, often written before or alongside coding. It usually includes:

• Program name and brief purpose
• Inputs: files (name, organization, key), parameters, screens
• Outputs: files, reports, return codes, messages
• Processing logic in plain language (steps, conditions, formulas)
• Error handling and abend behavior
• Dependencies: copybooks, called programs, CICS or batch environment

The spec can be a separate document (Word, Wiki) or a long REMARKS/comment block. When the program changes, update the spec so it does not go stale.

Step-by-Step: Adding Documentation to a Program

• Set PROGRAM-ID to a clear, unique name (remember: first 8 characters often matter on mainframes).
• Add or update REMARKS with program purpose, main inputs and outputs, and called programs.
• Before each major section (e.g. open files, main loop, close), add a short comment block (lines with * in column 7) describing what the section does.
• Next to complex or non-obvious logic, add a brief comment or >* inline comment explaining why (e.g. business rule, timing assumption).
• When you change the program, update REMARKS or the change log if your standards require it.

What Not to Document

Avoid cluttering the code with comments that restate the obvious. For example, "Move A to B" next to MOVE A TO B adds no value. Do not comment every line. Prefer clear names and a few well-placed comments that explain why something is done or what a non-obvious value means.

Best Practices

• Keep documentation close to the code (REMARKS, section comments) so it is updated when the code changes.
• Use REMARKS for program-level description; use comments for section-level and line-level explanation.
• Comment the "why" and non-obvious rules; avoid commenting the obvious.
• Use a consistent style for section headers (e.g. *--- section name ---) so sections are easy to find.
• If you use a program spec, keep it in sync with the program when behavior or interfaces change.

Practice Exercises

Exercise 1: REMARKS block

Take a small program (or write a minimal one) and add a REMARKS block that states purpose, input file, output file, and one called program (or "none").

Exercise 2: Section comments

Add comment blocks (lines with * in column 7) before each logical section of a program: file open, main loop, file close. Use a consistent style.

Exercise 3: Inline comment

Find one non-obvious condition or calculation and add a >* comment on the same line or the line above explaining why it is there.

Related Concepts