Comments in COBOL

Comments

Summary Comments

Some comments summarize what would be reasonably obvious to anyone who took the time to read the COBOL code. Since their purpose is to save time, they should be as brief as possible. A line-by-line paraphrase of simple code would just get in the way.

Explanatory Comments

Other comments explain what would otherwise not be obvious. They may, for example:

explain tricky, complex, or unusual code.

explain peculiarities of the requirements.

explain why the program does something one way rather than some other, more conventional way.

suggest possible ways to enhance or modify the program.

warn of certain pitfalls ('IF YOU ENLARGE THE FOO TABLE, BE SURE TO CHANGE THE VALUE OF FOO-MAX').

Explanatory comments may need to be extensive. As in any other form of writing, don't be too verbose. But don't skimp. You may be reading those comments yourself some day.

Guidelines

Comments are generally a Good Thing. We all curse the programmer who writes a 2000-line program with no comments.

Still, even comments can be abused or misused. Here are some guidelines.

Include comments near the beginning of the program to describe its overall purpose and to summarize the change history.

Write a comment block at the beginning of every paragraph, summarizing what the paragraph does.
This guideline does not apply to a trivial EXIT paragraph. On the other hand, if you don't use GO TOs or fall-through logic, you don't need EXIT paragraphs anyway.

So far as possible, make your code readable and self-documenting, so that comments are not necessary.

Occasionally, and only where needed, add comments within a paragraph to clarify things which would not otherwise be obvious.

Comments should be as long as necessary, and no longer. Alternatively: Comments should be as short as possible, and no shorter.

When you change the code, change the comments as needed. Don't let the comments become out of date.

Since no one always follows the previous rule: don't trust comments.

COBOL Home

COBOL Style Forum