Generating code explanations

Edit online

Generate detailed, AI-powered explanations that help you understand COBOL, JCL, PL/I, REXX, and Assembler programs. You can generate explanations either through a workflow or by using a prompt.

Generate a comprehensive explanation using workflow

To generate a comprehensive workflow-based explanation, complete the following steps:

  1. Open IBM® Bob workspace with all extensions installed.
  2. In the IBM Bob chat window, click the Start Workflow icon (Play button), select Explain code, and then click Start.
  3. Select the program file for which you need an explanation.
  4. Select an explanation perspective:
    • Architect - Focuses on system design, integration points, and technology stack.
    • Developer - Focuses on execution flow, processing steps, and technical implementation.
    • Business - Focuses on business purpose, user interactions, and operational importance.
  5. The system retrieves data dictionary, validates dependencies, and generates a comprehensive explanation that includes purpose, interfaces, dependencies, and processing flow.
  6. The explanation is saved to docs/explain/<perspective_programname>.md.
Note: To view the flow diagram in the generated document, right-click the file and select Open Preview.

Generate an explanation using a prompt

You can also generate explanations directly by typing a request:

  1. Open IBM Bob workspace with all extensions installed and select Z Code or Z Architect mode.
  2. In the chat window, use the /explain command to generate an explanation for a program. For example:
    /explain {program_name}.cbl
  3. The system automatically activates the explain skill and creates a TODO list.
  4. It checks for the data dictionary (DD.json) and retrieves the metadata. If unavailable, the workflow continues without it.
    Note: For more information about the data dictionary, see Working with a data dictionary.
  5. The system identifies the required perspective based on the selected mode:
    • Z code - Developer-focused, emphasizing execution flow, processing steps, and technical implementation.
    • Z Architect - Architect-focused, emphasizing system design, integration points, and technology stack.
  6. The system displays a comprehensive explanation including purpose, interfaces, dependencies, and processing flow.
Note: Natural language prompts such as explain what {program_name} does might either start a workflow or trigger the explain skill to generate explanations.

Tools

To know about the tools used by IBM Bob Premium Package for Z to generate explanations, see Using workflows, skills, tools, and commands.

Sample prompts

You can use the following sample prompts to generate explanations:

  • Explain what @{folder_name}{program_name} does
  • Explain @{folder_name} {program_name}
  • Explain the business logic in this code section
  • Analyze this CICS transaction handler
  • What does this JCL job do?