Working with legacy code can be challenging for developers, especially when the code is complex or not well-documented. In such cases, it can be helpful to use Copilot Chat to explain unclear or complex code to other developers or to document it for future reference.
Example scenario
The block of COBOL below connects to a database and inserts a record. The code lacks documentation, which makes it difficult to understand what it does and how it works.
IDENTIFICATION DIVISION.
PROGRAM-ID. INSERT-RECORD.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-STATUS-FLAGS.
05 WS-DB-STATUS PIC X(2).
88 WS-SUCCESS VALUE "00".
05 WS-SQLCODE PIC S9(9) COMP.
05 WS-ERROR-MSG PIC X(50).
LINKAGE SECTION.
01 LS-PARAMETERS.
05 LS-PERSON-RECORD.
10 PERSON-ID PIC 9(6).
10 PERSON-NAME PIC X(50).
10 PERSON-AGE PIC 9(3).
05 LS-RESULT PIC X.
88 SUCCESS VALUE 'T'.
88 FAILED VALUE 'F'.
PROCEDURE DIVISION USING LS-PARAMETERS.
PERFORM INSERT-AND-VALIDATE
GOBACK
.
INSERT-AND-VALIDATE.
EXEC SQL
INSERT INTO persons (id, name, age)
VALUES (:PERSON-ID, :PERSON-NAME, :PERSON-AGE)
END-EXEC
IF SQLCODE = 0
EXEC SQL COMMIT END-EXEC
SET SUCCESS TO TRUE
ELSE
EXEC SQL ROLLBACK END-EXEC
SET FAILED TO TRUE
STRING "DB Error: " SQLCODE
DELIMITED BY SIZE
INTO WS-ERROR-MSG
DISPLAY WS-ERROR-MSG
END-IF
.
Example prompt
We can use a simple prompt to ask Copilot Chat to add documentation to the code.
Note
If you want the documentation generated in another format like Markdown, you can specify the desired output format in the prompt. For example: Document this code in Markdown.
Example response
Note
The following response is an example. Copilot Chat responses are non-deterministic, so you may get a different response from the one shown here.
Copilot will provide a text overview of the code block, and an updated version with comments explaining the logic and purpose of each section.
For example:
*****************************************************************
* Program: INSERT-RECORD
* Purpose: Inserts a person record into the database with
* transaction management and error handling
*****************************************************************
IDENTIFICATION DIVISION.
PROGRAM-ID. INSERT-RECORD.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
* Status flags and error handling variables
01 WS-STATUS-FLAGS.
05 WS-DB-STATUS PIC X(2). *> Database status
88 WS-SUCCESS VALUE "00". *> Success flag
05 WS-SQLCODE PIC S9(9) COMP. *> SQL return code
05 WS-ERROR-MSG PIC X(50). *> Error message
LINKAGE SECTION.
* Input/Output parameters
01 LS-PARAMETERS.
05 LS-PERSON-RECORD.
10 PERSON-ID PIC 9(6). *> Person ID
10 PERSON-NAME PIC X(50). *> Person name
10 PERSON-AGE PIC 9(3). *> Person age
05 LS-RESULT PIC X. *> Operation result
88 SUCCESS VALUE 'T'. *> Success flag
88 FAILED VALUE 'F'. *> Failure flag
PROCEDURE DIVISION USING LS-PARAMETERS.
PERFORM INSERT-AND-VALIDATE
GOBACK
.
*****************************************************************
* Handles database insertion with transaction management
*****************************************************************
INSERT-AND-VALIDATE.
EXEC SQL
INSERT INTO persons (id, name, age)
VALUES (:PERSON-ID, :PERSON-NAME, :PERSON-AGE)
END-EXEC
IF SQLCODE = 0
EXEC SQL COMMIT END-EXEC *> Commit if successful
SET SUCCESS TO TRUE
ELSE
EXEC SQL ROLLBACK END-EXEC *> Rollback if failed
SET FAILED TO TRUE
STRING "DB Error: " SQLCODE
DELIMITED BY SIZE
INTO WS-ERROR-MSG
DISPLAY WS-ERROR-MSG
END-IF
.