Easytrieve Comments Best Practices

What Good Comments Accomplish

Comments transfer context cheaply: business rules, data dependencies, expected job schedule, comparison baselines for parallel runs, and caveats for COMPAT mode compiles. They do not replace readable names or modular macros—they supplement them when logic must stay opaque for historical reasons. A comment should answer questions a reviewer asks in the first five minutes: What input files? What outputs? Who owns this? What breaks if I remove this SORT?

Program Header Block

Every production member deserves a header at the top of the Library section: program title, purpose, author or team, creation date, last significant change date, change ticket id, input and output files, schedule frequency, and dependency notes (must run after job PAYIN). Keep headers maintained—an header listing 2003 owner when the 2024 team owns maintenance misleads on-call staff.

1
2
3
4
5
6
7
8
9
*================================================================
* PROGRAM : PAYDEPT
* PURPOSE : Department 911 payroll detail report for HR audit
* OWNER   : Finance Apps team / CMDB app EZT-PAYDEPT
* INPUT   : PAYROLL DD - daily extract from HR system
* OUTPUT  : PRINT PAY-RPT to spool class X for archive
* SCHED   : Daily 06:00 after JOB HR-PAY-EXTRACT
* CHG     : CHG55421 2026-03-01 added PAY-GROSS filter per audit
*================================================================

FILE and Macro Comments

FILE blocks document physical reality: copybook name, record length, layout version, effective date, and contact for layout changes. When positions shift, comment old and new positions during migration window. Macros carry the canonical comment—application programs should not duplicate entire layout essays if they %INCLUDE the macro.

Business Rule Comments

Place business rule comments immediately above the IF or CASE enforcing them—not in header only. Regulators reading listings see rule and code together. Reference policy document id when applicable (FIN-POL-012). Explain inclusive versus exclusive bounds: IF PAY-GROSS GE 50000 means include exactly 50000.00 per policy memo 2024-07. Temporary regulatory waivers get expiration date in comment so someone removes them.

Technical and Environmental Comments

Note when program requires COMPAT PARM, specific SORT product options, WORKFILE DD, or REGION=0M. Document assumed sort order if program omits SORT expecting pre-sorted input—common source of wrong control breaks. Online programs comment transaction id, map set, and pseudo-conversational resume points. Avoid embedding passwords, API keys, or personal data in comments—listings copy to wide audiences.

Change History Discipline

Prefer change control system as authoritative history; use header CHG line for last major edit rather than entire scroll of every typo fix. For significant branch, add dated comment above changed block. When removing code, comment why (CHG123 retired dept 444 per project X)—do not leave commented-out dead code indefinitely unless migration plan documents pending removal date.

Inline Versus Block Comments

Full-line star comments suit paragraphs and headers. End-of-line comments suit short clarifications after flags: FLG-EOF W 1 A * SET BY GET WHEN FILE EXHAUSTED. Do not push end-of-line past column 72 if shop limits line length—wrap to next line. Block comments with asterisk borders improve macro readability in expanded listings.

PROC and Procedure Comments

Each reusable PROC gets a one-line purpose comment before PROC line: * VALIDATE DEPT AND PAY PERIOD. Document parameters if PROC uses macro arguments or shared fields—what must be set before PERFORM. Special-name procedures note restrictions (no GOTO SCREEN in BEFORE-SCREEN) when team includes junior maintainers.

REPORT Layout Comments

Comment non-obvious mask formats, suppressed columns for legal holds, and control break levels when multiple BREAK commands interact. TITLE text alone may not explain that column three is year-to-date only after July—say so in comment above REPORT block.

When Not to Comment

• Restating IF DEPT EQ 911 when DEPT and policy are obvious from names.
• Commenting every PRINT—noise hides important notes.
• Leaving wrong comments after code change—update or delete.
• Pasting email threads—summarize decision in one line.
• Documenting language tutorial material available in TechDocs.

Comments and Listings in Audit

Auditors often request compile listings with source. Comments demonstrating awareness of regulatory filters support control narratives. Ensure LIST PARM in review compiles includes comments. Sensitive commentary belongs in controlled wiki linked by ticket id, not in source, when it reveals unreleased business strategy.

Keeping Comments Accurate

1. Update header CHG line on every production promotion.
2. Review comments in same code review pass as logic.
3. Reject pull requests with stale rule comments contradicting IF.
4. Quarterly scan top jobs for header owner and schedule accuracy.
5. During migration, note COMPAT and rename mapping in macro header.

Explain It Like I'm Five

Comments are sticky notes on your LEGO build so the next kid knows which pieces cannot come off. They should say why the bridge is short, not say this is a red block when everyone sees red. Wrong sticky notes are worse than none—they send someone to break the bridge. Update the note when you change the build.

Exercises

1. Write a program header for a fictional PAYDEPT report.
2. Add a business rule comment above a non-obvious IF threshold.
3. Identify one stale comment anti-pattern in legacy sample source.
4. List four FILE macro header fields you would require.
5. Rewrite a comment that restates syntax into one that explains why.