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";
In spaces using action code in the Inspector and in notes using the build-in Action prototype (e.g. Stamp and Library (function) notes in /Hints) commented lines are rendered in grey. this can be a useful tell-back
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.
Some considerations for effective use of comments
If you add comments to working code and it stops working, it may be gremlins in the parsing of the code causing the issue. What's clear to the human eye, may be less so to code trying to parse the code text. If adding comments causes a problem, don't overlook making a copy or your current code elsewhere and then deleting all the comments; doing so can save hours of frustration chasing wrong causes. If this type of problem occurs it may be one of the issues below. Meanwhile work is ongoing to resolve these edge-cases.
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: double forward slashes inside a string (false code colouring results)
This can occur if something like a web url is contained in a string. consider this:
$Text = "https://example.com";
In a code input box, everything from the '//' will colour as a comment, but the action actually works—setting a $Text value. This is an edge case for the code-colouring syntax as the differing intent of '//' is not obvious to the code-parsing regular expression.
If the problem faced is trying to see the syntax (colouring) is the now-comment-coloured part of the code, temporarily delete one of the two slashes and de-dub the test of the action before re-inserting the slash.
Another workaround is to move the slashes into a variable:
var:string vSlashes = "//";
$Text = "https:"+vSlashes+"example.com";
Although needing an extra code expression/line, this has the same outcome as the previous example but should make the main section of code colour correctly.
Avoid: unmatched quotes
Within a single comment (or single comment line in multi-line) always pair quotes. Assume an 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.