Action code may contain comments. A comment is part of the overall code but which is not executed when the code is run. This allows annotation within code. Such comments should be brief, and usually indicate something about the intent of the code before or after it (depending on comment placement).
Comments are useful. The working of some complex code may be obvious now, but will it be when re-visited several years later?
A comment begins with two slashes, and ends either with a second pair of slashes or at the end of the line. To write a multi-line comment simple start each line of the comment with a double forward slash. For example:
// this is a comment that
// continues onto
// several lines
$Color = "blue";
The above shows comments on a discrete line or continued on successive lines by simply starting the next line of comment with the same marker. The next example shows the two other forms. The first line of code shows a to-end-of current-line comment and the second line a fulling inline comment with valid code before/after the comment. Example, of line end and inline comments
if($Prototype=="Task") { // special handling for tasks
$Width= // 5 // 7;
}To recap, the three forms of comment are, in order of reading:
- a multi-line comment. Essentially, from a code perspective, this is a series of successive whole line comments.
- a line-end comment. Here, the comment continues to the end of the line, but does not affect the running of the code on the beginning of that line.
- an inline comment, i.e. within the content of a single line. The comment on the last line skips over the "5", starting before that figure and closing after it. This means that when run, $Width is set to 7 rather than 5.
Avoid: soft line-wrap
Action code has no explicit multi-line comment (although colouring my imply this. Avoid guesswork, and so do not rely on the text area's RTF ruler's soft-line-wrap. Best practice is to put explicit line breaks after a suitable width of code in the $Text and then start a new comment line (as above) with the continuing comment text.
Avoid: unmatched quotes
Within a single comment (or single comment line in multi-line) always pair quotes. Assume a on odd number of single or double straight quotes may and likely will cause a silent failure. The code parser and the code colouring processes work slightly differently. So either pair quotes or use 'curly' quotes . Thus, Opt+Shift+] will give a single right curly quote for an apostrophe (or, avoid speech-like contractions).
Examples of what to avoid
1. Unpaired single quotes.
BAD. Unpaired straight quote:
// don't do this.
GOOD. Uses curly quote for apostrophe:
// don’t do this.
GOOD. Avoid speech-style contraction:
// do not do this.
2. Unpaired double quotes
BAD. Unpaired double quote in wrapped comment text.
// Here is "Some
// wrapped quoted text". Etc...GOOD. Wrapped partial quote is fully quote-enclosed:
// Here is "Some…"
// "...wrapped quoted text". Etc...GOOD. Uses curly double quotes for quoted text:
// Here is “Some
// wrapped quoted text”. Etc...Avoiding contractions is also likely kinder to translation used by those whose first language differs from our own.