Here are 10 tips (for now) to help you along your scripting journey. These tips are in no particular order.

Use Aliases

There are currently 3 methods for accessing data from a custom field:

• By Name

• By ID

• By SIL Alias

However, only one of these methods is recommended, see below for more details.

Name – While generally readable, the names of custom fields can be changed by admins who may not be aware that they are being used in a script. This could cause the scripts to not be able to access the data for the custom field.

ID – While less breakable than using the field name, custom field id’s can make a script hard to read. Also, the script can’t easily be migrated to another instance since the id’s could be different.

SIL Alias – While an extra setup step is required, aliases make the scripts readable, protect against name changes, and allow scripts to be migrated without requiring updates.

Comments

It’s pretty much guaranteed that your code will be modified or updated over time. It is also true that almost all developers will come across someone else’s code at one time or another. A bad habit among inexperienced programmers is to include little or no comments while coding.

RunnerLog

It is hard to debug scripts when you don’t know what is happening inside of it. Using the runnerLog() routine allows for information to be printed out to the script console. This information can include the value of variables of custom fields which can greatly aid in debugging. And, since the console only exists in two place, SIL Manager, and the SIL Runner dashboard gadget, the debug messages can be left in the code since they will not be visible when used with standard triggers like listeners and workflow functions.

Avoid Code Repetition

The purpose for most applications (or computers in general) is to automate repetitive tasks. This principle should be maintained in all code, even web applications. The same piece of code should not be repeated over and over again.

No Passwords

Since the most performant way to store SIL scripts is on the file system, it is not recommended to leave passwords inside them since the scripts can be opened by other users who may have access to those files. While a 100% secure method of storing the password does not yet exist, there are some strategies to make it much harder for any users with malicious intent. These include:

1. Using the encrypt/decrypt routines to obfuscate the password

2. Storing the password in a persistent variable

3. Storing the password in an external database

4. Storing the password in the Java Key Store and using the system() routine to retrieve it

Generally, using a combination of #1 and #2 is an effective enough solution. It would require the malicious user to be a Jira administrator in order to be able to run the scripts through the SIL Manager.

CSV/JSON Data Files

A simple script is a good script. Therefore, scripts should not contain information that can be considered data in them. Instead, SIL has a hidden gem of a feature that allows CSV or JSON files to be automatically converted into an array of structs. It is much cleaner to store the data separately and import it using this feature. It will also be easier to maintain or update the data in the future.

Breakup Large Files

The include function is very helpful for creating scripts that can be used by other scripts. If a script becomes too large it becomes difficult to read and harder to maintain. The include function can also come in handy in these situations since chunks of common logic can be broken out into separate files. This makes it much easier to consume each portion of the overall solution. And, it also helps keep the scripts maintainable and you may also find that one of the broken out scripts can become reusable as well.

For example, a general guideline on how to split up a large script could be this:

1. Separate any struct definitions into a separate file. These files that only contain structs are usually highly reusable.

2. Separate user defined functions into a separate file. Normally, the main body of the script can be understood without including the code for the function (as long as the function is properly named). Also, it creates a file that can easily be reused by other scripts that could benefit from the same functions.

3. Any required data should be stored in a separate CSV or JSON file.

4. Any other bits of code that could be considered “self contained” or otherwise logically grouped together can be broken out to another file.

As a general guideline, any script over 100 lines of code should be reviewed for possible ways to split it up and therefore more readable.

Code Versioning

Code versioning does not just include using tools like Git or Subversion (but it could). It can also be as simple as copying a script and adding a version number to its name. It is a good practice to adapt since it allows the code to be easily reverted should a problem be found with the new changes.

Logging

Again, you can’t troubleshoot a script while blind. You need to know information about the script or how/when it was triggered. Logging is a great solution for this. However, make sure the logs are actually valuable and you are don’t just spamming them since too much noise in the log file could make it harder to detect other issues that may be occurring in the system. Also, be aware that each log message requires an update from the file system. Putting to much stress on the file system by spamming the logs can actually dramatically slow down your system.

File Extensions

Use them… While not required it is possible to different types of files in the silprograms folder other than SIL scripts. The recommended file extensions are:

• For SIL scripts: .sil

• Text files: .txt

• CSV data files: .csv

• JavaScript files: .js

Contents