Snap, like other programming languages, is most effective when certain practices and guidelines are followed. To get the most out of Snap, it's best to keep these guidelines in mind to maximize maintainability and minimize bugs and other problems.
Keep your application secure
Remember the Snap rules you write for your configurator or scene are executed in one of two places: Server-side or local. Consider the best location for your code to balance needs for security and speed.
-
Server-Side rules
These rules are processed on the server: the Snap code is never sent to the user's workstation. For example, safe functions and pricing rules are server-side, and the best place to write any proprietary calculations or patented, sensitive lookups. Your customer only sees the result of the safe function, not how it was generated.
-
Local rules
These rules are processed on the user's workstation, tablet, or mobile phone. Because the are local to the user, they are very fast and responsive. However, it is possible for some users to look at the code within the rule as they can with the code on any web page. Local rules are the best place for code which runs often, needs to be fast, and does not contain sensitive calculations.
Learn more about where Snap rules are executed.
Break Down the Code
Don't Repeat Yourself
Comment your Code
Use the any Type Sparingly
All Snap logic can be broken down into multiple rules. Having all of your logic in one single place can make it difficult to troubleshoot problems in the future because it can be difficult to sort through the many blocks to find what you are looking for. Think of each rule as a paragraph in prose. Having all of the code in a single rule is similar to having a long document in one run-on paragraph. Your logic will often have different segments. For instance, for value rules in a configurator, it might be beneficial to separate the rules by page or group. This way if you notice a bug within a certain page of your configurator, you can more easily narrow down the cause to a single rule which has a small subset of the blocks used in the entire suite of rules.
There is a mantra in software known as DRY: Don't Repeat Yourself. DRY principles are a very effective way to maximize clean code and maintainability. Snap has functions and subroutines in place to accommodate this principle. Consider the following code:
This code repeats a lot of logic, and could be prone to problems if one of the instances has a typo (for instance, suppose the third line says "Wod" instead of "Wood"). Furthermore, if a change in the logic is needed, you'd have to apply it in three different places. In the above example, at least all of the repeated logic is in one place, but in practice, repeated logic is often scattered throughout the codebase, and can be hard to find all instances of it afterwards.
The solution is to refactor this logic into a subroutine that defines the common logic once, and then called multiple times.
By using a subroutine with a couple parameters, the code is simplified and there's only one place where the logic occurs.
Comments are important to illustrate what the Snap code does and why. Comments should be concise and informational. The comment should not state the obvious (e.g. "this adds 1 + 1") but rather should elaborate on its function. (e.g. "Sum up all the perimeters of red cubes"). Comments not only help others who may need to maintain the Snap code, but could benefit yourself, since you may need to remind yourself of how the code works later on.
Comments are searchable. When in a configurator or scene, click the search magnifying glass in the upper-right to open a search pane. You can find the text of any comment (along with the text within any Snap code written) in this box. Use this searchability to your advantage:
- create long-term comments (comments you intend to remain in the code), such as "REQ-1234" a reference to a feature number in the requirements document.
- create short-term comments (those you hope to remove soon), such as "#TODO: ask product owner about chamfers calculation".
In this way, it's easy to search for all the Snap code related to feature requirement 1234, or any of the little "to-do" questions you might have for the product owner.
Snap is a typed language, and specifying which types you expect are essential to code that can be followed and reduces bugs. For this reason, it's always a good idea to only use the any type when you really need to. If you know what type a function will always return, make sure you specify that type. This is similarly true when defining variables.
Use the Most Limited Scope Possible when Defining Variables
If a variable is only going to be used within a small subset of your code, it's best to define that variable within that small subset if possible. If you are defining many variables in the beginning of your rule in such a way that it is accessible throughout your code, the code can be difficult to follow along with, plus you will be unable to reuse names, which could result in many variables being given names like "width1", "width2", etc. without it being necessary if the proper scope was established for these variables.