Explaining and documenting code with AI

AI assistants can read a COBOL program or a JCL job and describe it in plain English, draft documentation and help you find what a change might touch. They are fast first readers, not authorities: everything they say is a draft you check against the source and the tools your site trusts.

What an AI assistant actually is

The assistants teams use for code are built on large language models: programs trained on huge amounts of text and code that predict a likely continuation of whatever you give them. They do not compile, run or look up your code unless a tool around them does that explicitly. When an assistant 'explains' a COBOL paragraph, it is producing a fluent description that is usually right and occasionally confidently wrong — a hallucination.

Products in this space include IBM watsonx Code Assistant for Z, general-purpose assistants built into editors such as VS Code, and in-house tools some banks build on approved models. Which one you may use is a decision for your organisation, not for you (see the AI governance course). Capabilities differ by product and version, so check your site's documentation rather than assuming.

Where it helps on the mainframe

Task	Typical value	How far to trust it
Explain an unfamiliar program	A readable summary of a 3,000-line program in minutes	Good starting map; verify every business rule you rely on
Explain a JCL job	What each step runs, which datasets it reads and writes, what DISP means here	High for syntax; check procs, symbols and overrides it cannot see
Draft documentation	Program headers, data flow notes, runbook first drafts	Edit before publishing; remove anything you cannot confirm
Support impact analysis	Suggest which paragraphs and fields a change touches	Low on its own; confirm with cross-reference tools and search
Code review assistance	Spot unused fields, missing FILE STATUS checks, odd logic	A second pair of eyes, never the only reviewer

How a good request is built

The quality of the answer depends heavily on what you give the assistant. A prompt pattern is a reusable shape for a request. A simple, dependable one for code explanation has four parts: role, context, task and output format, plus an instruction to flag uncertainty.

A prompt for explaining a paragraph (illustrative)

Role:    You are helping a junior developer read IBM Enterprise COBOL.
Context: Program PAYCALC. Copybook PAYREC is included below.
         Fields ending -AMT are PIC S9(7)V99 COMP-3 (packed decimal).
Task:    Explain paragraph 2100-APPLY-TAX in plain English.
Format:  1) one-line summary  2) step-by-step logic
         3) fields read and written  4) anything you are unsure of.
Rules:   Do not guess values from copybooks you cannot see.
         Say 'not visible in the input' instead.

The last part matters most. Assistants fill gaps with plausible guesses. Telling them to say what they cannot see turns silent guesses into visible questions you can answer from the source.

What the assistant cannot see

A COBOL program rarely stands alone. Its data layouts live in copybooks, its JCL calls procs with symbolic parameters and overrides, and its real behaviour depends on runtime data, DB2 tables and CICS resources. If you paste only the program, the assistant must invent the rest.

What context an explanation really needs

Usually provided

Program sourceThe JCL member you opened

Often missing

Copybooks and their versionsCataloged procs and symbol valuesCalled subprogramsDB2 table definitions

Never in the code

Business intent and historyProduction data volumesWhy a strange workaround exists

Impact analysis: AI as a helper, not the source of truth

When a field length changes, you need every program, copybook and job that touches it. Sites answer that with deterministic tools: source search in the editor or SCM, cross-reference listings, and dedicated analysis products. An assistant can help you read the results, suggest places to look and summarise a long list, but it can miss a program it was never shown. The authoritative list comes from search and cross-reference, not from the model.

Generating documentation that lasts

Give the assistant the program and the copybooks it includes.
Ask for a fixed structure: purpose, inputs, outputs, key rules, error handling.
Check each statement against the source; delete what you cannot confirm.
Add the business context only people know.
Store it next to the code in version control so it is reviewed with future changes.

TRY IT YOURSELF

In the prompt pattern above, what are the four core parts, in order? Type the first one only.

Show a hint

It tells the assistant who it is acting as.

Show the solution

Role, then context, task and output format, plus a rule to flag uncertainty.