Best practices for making a good open source 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.

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.

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.

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

Absolutely!

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:

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.)

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?

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.

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.

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.