Best Practices, Tips and Tricks¶
The following are best practices, tips and tricks for creating Lua scripts. Some are general programming advice, but are applicable here none the less.
Debug Output¶
Often you will want to print some text to the Debug Output File during development. But when the script is used in production, you don’t want or need to print this output. To accomplish this, it is helpful to have a single variable to control whether to print the debug output, and then wrap all print statements with an “if debug then”.
debug = true
if debug then print("Some Debug Message") end
Simply change the debug variable to false to turn off debug printing. This method provides you manual control. You can alternately use the built in API “System.IsDebugging”.
if System.IsDebugging then print("Some Debug Message") end
This will ensure you never print Debug on a Production system that has the “Enable Online Script Debugging” right click menu command disabled.
Style¶
All of Symetrix Lua Extensions have a consistent style. While you can decide what conventions you wish to employ, knowing our decisions may help you better understand the code, and allows you to use the same for consistency and improved readability. This includes the following:
· Variable Naming - Variables are named without spaces utilizing lower camel case
myCoolVariable
· Function Naming - Functions and Methods are named without spaces utilizing upper camel case.
MyCoolFunction
Comments¶
As is true with any programming language, comments are your friends. Utilize them as much as possible. In Lua, a comment starts with a double hyphen “--" anywhere outside a string. If the text immediately after -- is not an opening long bracket “[[“, the comment is a short comment, which runs until the end of the line. Otherwise, it is a long comment, which runs until the corresponding closing long bracket “]]”.
--This is a short comment. Anything on this line is a comment.
--[[This is a multiline long comment.
It continues on to following lines.
Until the comment ends like this.]]
Long comments are frequently used to disable code temporarily.
Avoid Magic Numbers¶
Instead of using special numbers in your code directly, where it is hard to add comments, use a variable with a descriptive name and a comment.
--Unclear
if x < 15 then print(“Will try again”) end
--More Clear
maxNumberOfIterations = 15 --More than this and we see problems
if x < maxNumberOfIterations then print(“Will try again”) end
Limit API Calls to firmware when possible¶
API calls to the firmware take up significant resources. So, if you need to use a value more than once, it is more efficient to store it as a variable.
--Less Efficient
DoSomething(NamedControl.GetValue ("MyFader"))
DoSomethingElse(NamedControl.GetValue ("MyFader"))
--More Efficient
Temp = NamedControl.GetValue ("MyFader")
DoSomething(Temp)
DoSomethingElse(Temp)
Plan for changing values¶
Due to implementation details, some API calls may change over time. For example, consider two successive calls to the same table:
print(Control.Inputs[1].Value)
print(Control.Inputs[1].Value)
These are not guaranteed to be the same thing, because the table is being updated asynchronously. If you need the values to be the same, it is always good practice to store them into a local variable. The most common application of this is to store all the NamedControls and Control.Inputs that you use into local variables at the beginning of a TimerClick() callback, and then use the local variables for the rest of that callback pass.
function TimerClick ()
--Store variables
input1 = Control.Inputs[1].Value
myFader = NamedControl.GetValue ("MyFader")
--Do stuff with those variables
print(input1)
print(myFader)
end
MyTimer = Timer.New()
MyTimer.EventHandler = TimerClick
MyTimer:Start(.25)
Allow User Control of Offline Connection¶
It’s best to allow the user to choose if they want their Intelligent Module to connect when the site is offline. This is helpful for a variety of reasons including to support devices that only allow a single connection, or to prevent strange operation when both the online and offline site are trying to change a device simultaneously. This can easily be done with an onscreen button that is checked within the timer callback function.
--get button state
offlineConnectButton = NamedControl.GetValue("ButtonOfflineConnect")
--establish if allowed to connect
if offlineConnectButton == 1 and Device.Offline then
allowConnect = true
elseif Device.Offline == false then
allowConnect = true
else
allowConnect = false
end
if allowConnect == true then
--do all the connection work and sending data
end
Argument Type Checking¶
If you are receiving a string from a user through the Control View, you should check that it is valid before using it. For example, if they are entering in an IP address, you could check to make sure is a valid IP address (see Handy Code Snippets) before using. Since the user can enter anything into a text field, you want to be sure it is in the proper format before your code attempts to use it. This will protect against bugs and crashing.
Source Control¶
If you are working on a large complicated script or if multiple people will be working on the same script, it can be helpful to utilize source control. Source Control allows you to track the changes in your code, work collaboratively on multiple parts simultaneously, and only use final versions once you are sure everything is working. It also allows you to properly create multiple versions and back up your code as you go.
One of the most common tools for doing this is with Git and Github.
Source control, Git and Github are large topics. It is beyond the scope of the Symetrix documentation, to teach them thoroughly. Instead, this document will point to the abundance of freely available reference material already available.
A great place to start is with this training series.
https://lab.github.com/githubtraining/first-day-on-github
Once you are setup and using Github, you can incorporate the benefits into your Intelligent Module creation workflow.
Stack Overflow¶
Like any other programming language, at some point, you will need to ask a question.
For general Lua programming questions, the first place to look is Stack Overflow.
https://stackoverflow.com/questions/tagged/lua
If you’ve never used it before, Stack Overflow is an incredible resource for programming information where people ask questions and get answers from the community. Chances are if you have a general question about Lua, someone else has asked it before and it has already received a great answer. Simply search Stack Overflow and you will almost always, find what you need.