| Commenting Code | KEVIN RESCHENBERG
04-02-2008 |
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 '*/
|
