Easytrieve Comments

Full-Line Asterisk Comments

When the first non-blank character in the statement area is an asterisk, the entire remainder of that 80-character record is a comment. The compiler ignores it for syntax and semantic analysis. Use full-line comments for section headers, change history notes, ticket references, and explanations longer than a few words.

1
2
3
4
5
6
* PAYROLL DETAIL EXTRACT - TICKET PAY-4402
* AUTHOR: FINANCE BATCH TEAM
* INPUT: PERSNL DD MUST MATCH FILE NAME PERSNL
 
FILE PERSNL FB(150 1800)
  EMPNO 1 5 N

Blank Line Comments

A source record that contains only blanks is also treated as a comment. Blank lines visually separate Library definitions from Activity logic or one JOB from another REPORT block. They cost nothing at compile time and improve scroll navigation in ISPF. Some shops discourage excessive blank lines in members with strict line-count policies—balance readability with local standards.

Inline Comments

To comment on the same line as code, complete a valid statement first, then code a period, one or more spaces, an asterisk, and the comment text. The period ends the executable statement; the asterisk begins commentary. Inline comments suit short clarifications tied to one IF or MOVE—not paragraph-length narratives better placed on full-line comments.

1
2
3
IF PAY-GROSS LT 300.99.  * special bonus tier threshold
   PERFORM SPECIAL-BONUS
END-IF

Comment Types Compared

Where Comments Cannot Go

Broadcom explicitly prohibits comments within a continued statement. If a MASK or PARM spans two lines joined by minus or plus continuation, you cannot insert an asterisk comment line between those physical records until the logical statement completes. Place comments immediately before the continued block or after the final continuation line. Violations produce compile errors referencing unexpected tokens on the continuation line.

Comments vs Compiler Listings

Comments do not generate executable instructions, but they may still appear in compiler listings depending on PARM listing options. Listings with source help auditors connect deployed load modules to documented business rules. When comments include ticket numbers and dates, production incident response speeds up because SYSPRINT listings point to change control records.

Documentation Best Practices

• Header comment block: program name, purpose, input files, DD names, owner team.
• Explain unusual GOTO JOB or PERFORM patterns that skip records.
• Document sort order assumptions before CONTROL break reports.
• Note migration reserved-word renames when upgrading to 11.6 function mode.
• Avoid restating obvious syntax—explain business why, not what MOVE does.

Comments in Production Maintenance

Operations teams sometimes read only JCL and comments when source access is restricted. A comment stating which report DD carries business output prevents misdirected incident tickets. When removing obsolete logic, update or delete stale comments—wrong comments harm more than no comments because they look authoritative.

Common Comment Mistakes

1. Using * mid-line without period-space after a complete statement for inline form.
2. Comment lines inside continued statements.
3. Assuming comments fix undefined field errors—they do not.
4. Embedding change passwords or internal URLs in comments visible in listings.
5. Leaving commented-out executable code that confuses reviewers about active logic.

Explain It Like I'm Five

Comments are sticky notes on a recipe that the kitchen robot ignores when cooking. A star at the start of a line means the whole line is a note. A dot then star after an instruction means a tiny note on that one step. Empty lines are blank sticky notes for spacing. You cannot stick a note in the middle of a sentence that continues on the next line—you wait until the sentence finishes.

Exercises

1. Write a five-line header comment block for a payroll JOB program.
2. Add an inline comment to an IF that filters department ACC.
3. Explain why a comment cannot sit between two continuation lines.
4. Revise an over-commented MOVE line to remove noise and keep one business note.
5. List three facts a good program header comment should include.