April 2, 2008

Commenting Code

No, I'm not going to talk today about the fact that we should comment our code. (We should.) Instead I wanted to point out a few of the mechanics of it. You may be wondering what could possibly be new about commenting code, but I'll try to highlight a couple of quirks or things that might be useful.

In PeopleCode there are actually three ways of coding comments:

/* Comment */
rem Comment;
<* Comment *>

The first two are the most common. If you want to add a comment at the end of a statement you must use the /* */ construct. REM ("remark") is automatically moved to its own line.

Which one you use is a matter of preference, but there is one small danger with using REM. It ends with a semicolon. If you forget the semicolon, you are commenting out the next statement, perhaps unintentionally:

rem Now we do something very important.

DoVeryImportantWork();
DoSomethingElse();

Color syntax highlighting can help with this, as comments are green. However, there is an odd quirk involving REM and color syntax highlighting: the "REM" must be either all caps or all lower case, or the comment will not turn green.

REM This is green;
rem This is green;
Rem This is not!;

The <* *> construct is probably less well known. This one is handy when you want to comment out a large block of code. REM is not good for this purpose. /* */ could be used, but if the block already contains /* */ comments, then you have a problem. Use <* *> in this case and the entire block will be commented out, regardless of whether it contains other comments. Just about anything will be commented out by <* *>, except for one odd case—unmatched quotes. For some reason <* *> will check for unmatched quotes while the other types (as expected) don't care.

SQL view text can be commented, although there are more restrictions. REM and <* *> don't work. /* */ will work, but it's not highlighted as a comment and any keywords within the comment (WHERE, AND, OR, etc.) turn blue. At some releases they turn into all caps, so your comment becomes something like

/* Here we SELECT employees WHERE the job code IS 123 */

Here's a trick you can use. Include a single or double quote with the comment markers. This turns everything into bright red, making it very easy to find within the SQL:

/*' Here we select employees where the job code is 123 '*/

Until next time...