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: either server-side within the cloud, or client-side within the user's browser. Consider the best location to balance needs for security and speed.
-
Server Side
Server-side code is executed on the server, and the results sent to the client. The Snap code itself is never sent to the user's device for execution. Server-side code is best for any proprietary calculations or patented, sensitive lookups. However, network latency does make this code slower.
Examples: pricing rules, workflow rules, safe functions, global functions. -
Client Side
Most other code is processed within the web browser on the user's device. Local to the user with no network latency, client-side code is fast and responsive. However, it is not as secure: some users could expose the logic or comments within the rule, as they can with any client-side javascript. Local rules are the best place for code which runs often, needs to be fast, and does not contain sensitive calculations or comments.
Examples: configurator rules, scene rules, global rules, etc.
You can easily mix and match your code, placing sensitive functions on the server and other code locally. Learn more about where Snap rules are executed.
Break Down the Code
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.
Don't Repeat Yourself
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.
Comment your Code
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.
Use the any Type Sparingly
Snap is a typed language, and specifying which types you expect is essential for creating code that is easy to maintain and limits many types of bugs. Therefore, use the any type only when you really need to.
- If you know what type a function will always return, make sure you specify that type.
- When defining variables, specify the type you expect, rather than using the catch-all any type.
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.