Commenting

Comments can be added in any area of the code editor. By default comments are coloured green. To add a whole line of comment, begin the line with an asterisk or slash. Anything added after the asterisk or slash will be a comment.

  cntry_fill_countries section.

    display 'Starting filling the countries data file!'.

* First check if file is not already filled

    move '' to cntry-name.

    exec cics
       startbr
          dataset('CNTRY_FILE')
          ridfld(cntry-name)
          resp(ws-resp)
    end-exec.

Comments can also be added at the end of a code line by entering two slashes after the line of code. Again anything added after the two slashes is a comment.

    evaluate ws-resp
       when 0           // NORMAL
          display 'Countries Data File already filled, skipping'
          go to cntry_fill_countries_end
       when 17          // IOERROR
          display 'IOERROR: Does the Data File exist?'
          go to cntry_fill_countries_end
       when 20          // EOF, empty existing file
          next sentence
       when other
          display 'ERROR: Unknown Error!'
          go to cntry_fill_countries_end
    end-evaluate.

Known issue: using a single quote in an inline two slashes comment, causes the comment to be displayed as normal code. This is a cosmetic problem only, the comment will be correctly parsed and generated as being a comment.

The asterisks and double slashes can also used to comment out lines of code, so that they are not executed.

Alerts in comments

Comments can be started with an alert, a specific keyword that is displayed in a noticeable background colour, in order to make the comment stand out.

Alerts come in three categories:

General warning, displayed in Yellow.
Indication of unfinished work, displayed in Red.
Explanatory note, displayed in Green.

To use an alert in a comment, the keyword has to be the first word in a comment with a single space separating the start of the comment marker or line, and the keyword itself. It is allowed to be prefixed by an at sign (@) and/or postfixed by a colon (:). Keywords are case insensitive.

The following keywords are accepted:

Yellow: warning, attention, headsup, heads up, heads-up, refactor
Red: todo, to do, fixme, fix me, tofix, to fix, bug, issue, unfinished, undone
Green: note, fyi

Example:

100-CALCULATE-ONE-SALES-TAX SECTION.

* @warning: Don't remove this section

* Note: This section is needed for ...

    evaluate ws-resp
       when 0           // @bug The problem is located ...
          next sentence
       when 17          // UnDone Lacks a ...