Comment Blocks

• Set off the comment block with a line of asterisks (or hyphens, or whatever) at the top and bottom.

  These lines make it easier to spot the boundaries between paragraphs. They also distinguish the comments at the top of the paragraph from any comments which you embed within the paragraph (which should usually not be set off with asterisk lines).

• Do not try to leave a neat border on the right-hand edge, as in the following 'flower-box' style:

  [Warning: bad code ahead]

          *****************************************************
          *2360-NOTE:                                         *
          *  DINDLE THE FRAMISTAN.                            *
          *****************************************************
  

  Those asterisks on the right edge of the box may look pretty, but they contribute nothing either to content or to readability. They're just a time-consuming nuisance to type.

  In particular, they discourage anyone from updating the comment block, because it's such a pain in the neck to keep those asterisks lined up. If someone sees a reason to improve the comments, the last thing we want to do is to put an obstacle in her way.

  (Arnold Trembley, a regular in comp.lang.cobol, offers an interesting counterargument.)

• Eliminate needless verbiage.

  Some people begin every comment block with 'THIS PARAGRAPH...', as in 'THIS PARAGRAPH DINDLES THE FRAMISTAN'. What a waste of typing. Of course we're referring to this paragraph. That's obvious. Just write 'DINDLE THE FRAMISTAN'.

  Naturally you should avoid excessive terseness as well. However, excessive verbosity is almost as bad.

• Use imperative verbs.

  For example, instead of writing 'DINDLES THE FRAMISTAN', write 'DINDLE THE FRAMISTAN'. First, you can eliminate verbiage (the subject of the sentence) and still be grammatical. Second, you type at least one fewer character.

  Okay, so I'm getting picky. That's what style guides are for. But it's easy enough to get into the habit of following this policy consistently.

• Don't hesitate to just repeat the paragraph name, if that's appropriate.

  Suppose you have a paragraph 2360-DINDLE-FRAMISTAN. If 'DINDLE THE FRAMISTAN' says all you need to say, then say it. Repeating the paragraph name like that may feel a little funny, but at least it reassures the reader that the paragraph doesn't do anything subtle or unexpected that would require further explanation.

  In Cobol nirvana, paragraph names would be self-documenting, and we wouldn't need comments. So if you find yourself repeating the paragraph name in a comment block -- congratulate yourself.

• When you make a substantive change to a paragraph, add a line or two to the comment block, giving the date, a brief summary of the change, and your name or initials. If those new comments aren't enough to make it clear what the change was, add another comment within the paragraph, at the point of the change.

  Usually these comments are a waste of time, but you can't tell in advance. Every once in a while, one of these archaeological tidbits provides just the clue I need.

COBOL home

COBOL Style Forum