Martin: Created page with "== 3. Comment Standards == === 3.1 Program Header Block === Every program must open with the following header block immediately after IDENTIFICATION DIVISION: ================================================================ PROGRAM : PROG-NAME * PURPOSE : One-line description of business function * AUTHOR : Developer name * DATE : YYYY-MM-DD * VERSION : 1.0 *--------------------------..."

2026-03-25T11:12:03Z

Created page with "== 3. Comment Standards == === 3.1 Program Header Block === 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 *--------------------------..."

New page

== 3. Comment Standards ==

=== 3.1 Program Header Block ===

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 ===

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 ===

* 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: <code>*YYYY-MM-DD disabled because <reason></code>
* Never leave an empty WHEN OTHER in an EVALUATE — add at minimum a comment explaining why no action is taken.

----

----
''[[Cobol programming standards|← Back to index]]''

COBOL Std 3 Comment Standards - Revision history