Best practices for making a good open source script

[Shrey_Banga]

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:

• 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:

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

[Bill_French]

Shrey_Banga:

a few best practices for open sourcing a script

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.

[kuovonne]

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.

[kuovonne]

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.

[kuovonne]

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.

[kuovonne]

Bill.French:

Overreaching a bit here…

Not at all. We come from very different backgrounds, and I appreciate the redirect. I tend to think more of the many people who will be writing scripts, despite never coding before. I’m serious. I’m one of them. I spent the majority of my life actively believing that I would never be a coder. Then I met Airtable.

Bill.French:

these items are now drifting

I eventually realized that, which is why I put in the “generic best practices” line.

Bill.French:

I think the spirit of this thread is to encourage some basic processes that will help developers ensure users can access and use scripts that are openly published. And to help developers leverage tools at hand to expose script efficiently and in an orderly manner.

Absolutely!

Bill.French:

Yeah, perhaps, but bear in mind - some script blocks are less than 5 lines of code and predominantly (as in vastly) Airtable users have chosen Airtable because they have no idea what GitHub is or what GitHub does. :winking_face:

That is why I prefaced that comment with if your code is particularly complicated. Plus, using Airtable is what led me to GitHub. :winking_face:

[kuovonne]

Here’s another suggestion. Although it might be considered a business requirement, it is Airtable specific:

If your script requires a specific base configuration (specific tables, fields, etc.) clearly document it. Although any sample base will include the required configuration, it will also likely include at least some additional data. Plus, users may have to manually create the configuration, which is easier if they don’t have to flip back and forth between the sample base and their base.

For example

• a script could calculate multiple values and need fields to store them in. Document those fields that the user must create and include suggested field types and options. (For example, if a date/time field should be local or global, or if a number should be a negative decimal.)

• a script could calculate a desired value based on a rollup that doesn’t exist yet. (It can be easier to create the rollup versus creating that logic in a script.) Clearly document the formula for the rollup. (Especially if you need a specific COUNT or ARRAY formula.)

[kuovonne]

Bill.French:

Your points are very good advice for anyone who might build applications or even create simple script blocks.

…
The circle of best practices for code sharing should be carefully drawn. But with each expansion on that idea, the circumference (like a forest fire) grows massively very quickly. Just sayi

Thanks. I certainly don’t want to stifle code sharing. As a self-taught scripter/coder/formula-maker, I have greatly benefited by the sharing of others. Can you suggest a different venue for where I should post my ideas about sharing scripts?

Bill.French:

If you overwhelm users -…, you risk setting the bar too high and sharing actually subsides instead of taking off.

Perhaps we need a favorite tips & tricks for writing scripts, similar to this old topic asking What are your favorite Airtable tips & tricks. I know that I would have loved to discover those tips early on in one fell swoop. By the time I found that thread, I already knew half of the tips, either by stumbling upon them in other threads, reading the documentation, or coming up with them on my own. (BTW, I’m still in absolute awe at the circular-references workaround posted there. Yet, as brilliant as it is, the scripting block makes it obsolete.)

On the other hand, I think that best practices for sharing scripts is different from best practices for writing scripts.

Bill.French:

Airtable was initially a “code-free” platform, the vast user base was drawn to it to avoid exactly the things we are now suggesting are important.

I defer to your greater knowledge because you know far more people who use Airtable than I do. In my much more limited experience, people like Airtable because of the ease of use.

But something doesn’t have to be code-free in order to be easy to use. I think adding coding/scripting to Airtable makes it even more attractive, because it makes Airtable even easier to use.

You don’t have to write code to use Airtable, just like you don’t have to write code to use Microsoft Access, Excel, or Word, even though all of them have had extremely powerful scripting capabilities for decades. The vast majority of MS Access users never write a line of code, but they still use MS Access databases that have scripts written by others.

I suspect that something similar will happen with the Scripting block. Eventually, most users who run Scripting Blocks will be running scripts that they themselves did not write.

---

My appologies for drifting again, as a (relatively) new member of the community, I’m still finding my way around here.

[Bill_French]

kuovonne:

Can you suggest a different venue for where I should post my ideas about sharing scripts?

The Airtable community is the right forum. And a dedicated topic perhaps - “Best Practices for Making Great Script Blocks” would be very welcomed guideposts especially for new script block users.