Help

Best practices for making a good open source script

Topic Labels: Scripting extentions
2070 8
cancel
Showing results for 
Search instead for 
Did you mean: 

We’re excited to see so many of you testing out the scripting block! We’re hoping lots of you will be open to sharing the scripts you write with the rest of the community, too. In that spirit, the platform team wanted to share a few best practices for open sourcing a script:

  • Include comments to explain what each part of your script does so others can understand and adjust for their own bases.
  • Give any variables or functions descriptive names to make your script easier to read and understand.
  • When posting code on the forum, use triple-backticks before and after your code to enable code formatting and coloring:

Screen Shot 2020-03-01 at 4.51.15 PM

  • Use input.tableAsync , input.viewAsync , input.fieldAsync and input.recordAsync to avoid references to specific fields or tables that might be different for other users. If you do reference specific fields or tables directly in your script, we recommend pulling them out into variables and moving them to the top of the script so others can change them to match their own bases.
  • When open sourcing a script, also share a copy of the matching base on Airtable Universe so others can see the script in context. Make sure the “Show code in public shares” setting is enabled for your script in this base so people can read and copy it:

Screen Shot 2020-02-26 at 4.23.10 PM

That’s it! Have any best practices or tips of your own? Share below :arrow_down:

8 Replies 8

My [additional] nominations…

  • Build and test your script blocks intended for open sharing in a separate base so that you can manage and test different versions when suggestions and changes occur.
  • Use the base as your open-source project manager by allowing conversations and community support to occur in the natural climate of Airtable.
  • Establish a table in the base for tracking changes, bug fixes, etc. and host a form to capture ideas and bugs.
  • Version your releases with an easily-recognized format mand include the version number in the script block’s display so there’s no confusion when users have issues.
  • Create another table in the base to track all community conversations about your script block; this will provide users with extended support resources and a knowledge base surrounding your script block’s history. Extra points - build a script block to automatically harvest all community mentions of your script block.

Let possible users know the target audience for the script

  • All Users This type of script should need no customization. Users should be able to copy/paste the entire script into the block and have it work immediately.
  • Novice Users This type of script needs minimum customization, but users do not need to know any JavaScript. Include variables at the top of the script. Also include a comment line telling users not to touch the code below the line.
  • Beginning Scripters Users must be familiar with the basics of JavaScript to use this script. It requires very simple customization beyond simply setting variables at the top.
  • Intermediate Scripters Users must know JavaScript at an intermediate level. Users do not need to know 3rd party tools in order to understand, customize, and use the script. Users might build their own functions to call functions in your script.
  • Advanced Scripters Users must know JavaScript at an advanced level and/or know additional tools (3rd party APIs, etc.) in order to understand, customize, and use the script. Users might build their own methods/functions/objects on top of your script.

If you code is particularly complicated and might undergo revisions, consider putting it in a public GitHub repository. Include the link to the repository.

Explicitly state the licensing for the code in the comments near the top of the script. There are a variety of possible open source licenses. Some companies have very strict rules about what software licenses they allow their employees to use and prohibit the use of unlicensed code.

If your code will change data in any way

  • provide a preview of the changes in the data
  • give a count of the specific number of records changed
  • ask for confirmation before proceeding

Consider having an undo as the last step of the script. Once the script completes, the ability to undo changes can be very difficult, if not impossible. While a true undo is not possible, you can

  • Implement the reverse of whatever changes you made (e.g. delete records that are added)
  • Store the initial data for the records, then update the records again with the original data

Follow generic best practices for coding.