Comments make applications easier to understand. It is highly recommended that CSPro applications be documented through the liberal use of comments. While editing logic and message files, comments are displayed as green text.
Within logic, they are used to explain the purpose of specific statements or to temporarily disable statements to help find errors. Within message files comments can be used to clarify the syntax listed in a message, or to identify "ownership" of the message or message blocks (i.e., what code blocks use the messages?).
There are two ways to mark text as a comment. The first method is to use two forward slashes: //. Everything on the line that follows the slashes is a comment. This is useful when you just want to insert a comment at the end of a line, or to comment a few lines of code.
The second method is to use multiline comments, starting with /* and ending in */. As soon as the /* is encountered, all subsequent text is considered a comment until the closing sequence */ is encountered. Multiline comments are useful when you want to comment many lines of text, as you only need to mark the start and end of the block; or if you want to embed a comment in the middle of a line of logic but want the rest of the line to be evaluated.
Comments can be placed anywhere in your logic. Because comments are ignored by the compiler, they will not be checked for syntax errors. Comments can be nested; that is, comments within comments are allowed.
Three styles of comments are allowed in
message files: single-line comments (
//), and both the new and old logic versions of multiline comments (
/* */,
{ }). When commenting message files, the start of the comment must appear at the beginning of a line. Unlike in logic, multiline comments cannot appear in the middle of a line. A multiline comment can end on the same line that it started, or at the beginning of a subsequent line.
/* Do not allow June to have more than 30 days
or for July to have more than 31 days. */
if ( HHMONTH = 6 /* June */ and HHDAY > 30 ) or
( HHMONTH = 7 /* July */ and HHDAY > 31 ) then
errmsg(1, "June", 30, HHDAY); // if error, then display message
reenter;
endif;
The first two lines are commented using a multiline comment. A multiline comment is also used, albeit on a single line, to indicate the month names. Following the
errmsg, a single-line comment marks the rest of that line as a comment.