Commenting
| Site: | QSC |
| Course: | Q-SYS Control 101 Training |
| Book: | Commenting |
| Printed by: | Guest user |
| Date: | Tuesday, 3 December 2024, 8:52 AM |
Description
Lesson Description
Use the Commenting tool to leave organizational and instructional notes within your Lua script or Block Controller.
Video Transcript
0:08
Let’s start our scripting lessons with commenting. As you start writing code, you’ll often
0:13
discover the desire to leave notes within that code. These are called comments, and you can leave
0:19
comments within the code about anything you want. This might be for your own organizational
0:24
purposes to label different sections, or you might use it to include instructions to other users who
0:30
might look at your code later on. These comments – HEY! Different kind of comments, come on get
0:35
back up here. A comment in code could be defined as information that is only intended for human
0:42
eyes, and gets ignored by the compiler. Basically, it has no effect whatsoever on the script.
0:48
First let’s look at Lua. To create a comment, simply type in two dashes. Anything you type after this
0:55
point will be considered a comment, and its color changes green to denote this. This comment is
1:01
specifically called a line comment, because it only comments out the line that you’re on.
1:06
When you proceed to the next code line, the script is grey again.
1:10
If you wanted to add multiple lines of comments, you could enter another double-dash, or you could
1:15
instead choose to use a “mutli-line” comment. To create a multi-line comment, you can add two
1:21
dashes, and then two open brackets. This will comment everything that follows, across as many code
1:27
lines as you wish until you end that comment with two closed brackets followed by two more dashes.
1:33
There is one slight anomaly in using this multi-line comment – what if, within your comment, you
1:39
need to include two closed brackets for some reason? You wouldn’t want to end the comment early
1:44
by including this in the text.
1:46
In this case, you could alter the double-brackets you’ve used to start your comment by adding an
1:52
equal sign between them, which basically changes the type of bookend you’re using to mark your
1:57
comment’s end points. You would then use this same symbol to close the multi-line
2:02
comment later on.
2:04
You could use this same idea with a double- or triple- equal sign if you needed additional layers of
2:10
unique bookends. This may seem extreme for something as simple as leaving comments, but
2:15
knowing about it now will help later on when we talk about some other ways of manipulating
2:19
strings. But for most cases, a simple double-dash will be all the comment you need,
2:25
or the traditional multi-line comment.
2:27
Switching over to the Block Controller, you can add a comment by looking in the System category,
2:33
and adding this block here. It clearly states “A comment for this block,” and you could then type your
2:39
comment into the text area.
2:41
Alternatively, you could build a comment directly into most blocks by right-clicking on the block and
2:47
selecting “Show Comment”. This embeds a Comment block into the top of the block, letting you use
2:53
this for titling, instructions, etc..
2:56
And if you navigate to the Lua tab, you can see that these comments are being created using the
3:02
same double-dash we just learned about, or even the double-bracket version for the comment block.
3:08
These comments may not appear green on this screen, but don’t forget that this white script page
3:14
cannot be edited. If you were to Convert your blocks to an editable scripting screen, then you’ll see
3:21
these comments as green type.
3:23
If you want to add comments to your Control Components, it’s as simple as adding labels!
3:29
If you were to use the Graphic Tools, you could add a Text Block, a Header, or a Group Box,
3:37
which are all fine ways of labelling your design or giving instructions
3:40
to someone else who’s looking at it.
3:43
You could also rename any of your Control Components just by selecting the component and typing a
3:48
new name, which could be a good way to describe its function – which is,
3:52
in essence, leaving a comment.
3:54
Go ahead and do a quick exercise with comments in the Control Worksheet,
3:58
and then move on to the next video.