COBOL Std 3 Comment Standards
Jump to navigation
Jump to search
3. Comment Standards[edit]
3.1 Program Header Block[edit]
Every program must open with the following header block immediately after IDENTIFICATION DIVISION:
<syntaxhighlight lang="cobol">
*================================================================
* PROGRAM : PROG-NAME
* PURPOSE : One-line description of business function
* AUTHOR : Developer name
* DATE : YYYY-MM-DD
* VERSION : 1.0
*----------------------------------------------------------------
* INPUTS : Source data — file names, ACCEPT fields, linkage
* OUTPUTS : Output file, console, database table
* CALLED BY: Parent program(s) or job step
* CALLS : Subprograms and copybooks used
*----------------------------------------------------------------
* CHANGE LOG:
* YYYY-MM-DD Author Description
*================================================================
</syntaxhighlight>
3.2 Paragraph Header Block[edit]
Every paragraph must be preceded by a comment block:
<syntaxhighlight lang="cobol">
*----------------------------------------------------------------
* R080-GET-NEXT-PRIME
* Purpose : Fetch next prime number from the open DB cursor
* Input : DAL-METHODS = 'next-prime'
* Output : DAL-PRIME-NUMBER, DAL-SEQUENCE populated
* Returns : DAL-RESULT 0=OK 1=ERROR 2=END-OF-DATA
*----------------------------------------------------------------
</syntaxhighlight>
3.3 Inline Comment Rules[edit]
- Comment the WHY, not the WHAT — the code shows what; the comment explains the business reason.
- Comment all 88-level condition names at point of definition and at point of test.
- Comment all EVALUATE WHEN branches with their business meaning.
- Comment all SQL statements with the purpose of the query.
- Commented-out code must carry the date and reason:
*YYYY-MM-DD disabled because <reason> - Never leave an empty WHEN OTHER in an EVALUATE — add at minimum a comment explaining why no action is taken.