ContentsUsing Comments
Comments are just bits of text that are completely ignored by AutoPlay. You can use comments to add notes to your scripts in order to make them easier to understand.
Note: Because the text will be ignored, you can write anything you want in a comment, and it will have no effect on how your application operates.
In AutoPlay, anything after two dashes (--) on a line is a comment. You can either put comments on their own line, like this:
-- Assign 10 to variable abc
abc = 10;
...or put them at the end of a line, like this:
abc = 10; -- assign 10 to abc
Both of the above examples do the exact same thing—the comments do not affect the script in any way.
You can also create multi-line comments by putting paired square brackets ([[ and ]]) around the comment text, like this:
--[[ This is
a multi-line
comment ]]
abc = 10;
Note: Comments are displayed in a different color that makes them easy to recognize in the script editor. (The comments are displayed in green by default, but you can change this color in the script editor settings.)
You should make a habit of adding comments to your scripts as you build them. If adding comments seems like a waste of time, consider how much time you will spend working on these scripts in the future. Complex scripts that make perfect sense to you now might take a few minutes to interpret the next time you need to make changes to a project. A few comments written while things are fresh in your mind can minimize the amount of re-thinking required.
Comments are especially important in a multi-user environment. If it's foreseeable at all that someone else may need to work on your project in the future, do your organization a favor and document your actions well.
Here are some tips for using comments:
Use comments to summarize large blocks of actions. This way, you only have to read the comment to know what the actions do. It's easier to read one line of text than it is to decipher a long list of actions.
Use comments to explain why an action is needed. This is especially important when the purpose of an action isn't obvious.
Use comments to highlight important actions, or to label different parts of your scripts so they're easier to find.
Use comments in a team environment to help keep track of changes (and who made them).
Use comments to document the decision process that led you to choose one approach over another. This could save you time if you ever find yourself considering other approaches again.
Use comments appropriately. Don't waste time explaining simple actions that are readily apparent.
Think of comments as investing a little bit of time now to save you a lot of time over the long run. You only have to write a comment once, but you will benefit from the comment many times over. In the long run, well-written comments will save you time, time and time again.
Tip: Use comments. You'll thank us later.
Here's a real-world example showing how a few comments can help clarify even a short, simple script.
First, the script without any comments:
nPos = String.ReverseFind(e_URL, "#", true);
if nPos then
strPage = String.Mid(e_URL, nPos + 1, -1);
Page.Jump(strPage);
end
The script is simple enough, but it becomes even clearer once some comments have been added:
----------------------------------------------------------------------
-- jump to a page when the user clicks on a link in this web object --
----------------------------------------------------------------------
-- search the target URL from right to left for a number sign (#)
nPos = String.ReverseFind(e_URL, "#", true);
-- did we find a # ?
if nPos then
-- get everything to the right of the #
strPage = String.Mid(e_URL, nPos + 1, -1);
--[[ jump to the page name that we extracted from
the URL. If there is no page by that name,
this Page.Jump won't do anything. ]]
Page.Jump(strPage);
end