Skip to main content

Hi,



Before I start sharing SNIPPETs or SCRIPTs that can be tried, commented, improved by the Community, I am a bit lost in how to introduce the shared SCRIPT…





  • What is in your opinion the best way to write a SCRIPT HEADER?


  • What are the effects/consequences between no HEADER and a very full HEADER.




If you would to take the time to answer me, I appreciate it very much, but please understand me: I am NOT asking these questions about the DOCUMENTATION of a SCRIPT which is another subject that has already been discussed here but about the lines that precede this documentation.



Moreover, all the SCRIPTs without header that I use as examples have been documented by their Author’s Threads who also provided the necessary BASE for self-testing.



Would I dare to say that my question is only about “legal” aspects ?



Examples picked from here:



Bill’s way:


/*



   ***********************************************************


   ScriptBloqs - ScriptChain


   Copyright (c) 2020 by Global Technologies Corporation


   ALL RIGHTS RESERVED


   ***********************************************************


   


*/


Mike’s way:



/**


 * Copyright 2020 Bocoup


 *


 * Permission is hereby granted, free of charge, to any person obtaining a copy


 * of this software and associated documentation files (the "Software"), to


 * deal in the Software without restriction, including without limitation the


 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or


 * sell copies of the Software, and to permit persons to whom the Software is


 * furnished to do so, subject to the following conditions:


 *


 * The above copyright notice and this permission notice shall be included in


 * all copies or substantial portions of the Software.


 *


 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR


 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,


 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE


 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER


 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING


 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS


 * IN THE SOFTWARE.


 */


Justin’s way: (No Header)



// Update these values based on your configuration





// Master table


let masterTableName =


Kuovonne’s way: (No Header)



// edit the table and field names to match your base


const tableName =


Openside’s way:



/*****


 * Title: Same Table Backlinks


 * License: MIT


 * Author: Openside (Team behind On2Air products and BuiltOnAir community)


 * Sites:


 * https://openside.com - Openside Consulting Services


 * https://openside.com/#products - On2Air Products


 * https://builtonair.com - All things Airtable Community


 * 


 * Reach out for all your Airtable needs


 *


Jonathan’s way:



// This is free and unencumbered software released into the public domain.


//


// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,


// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF


// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.


// IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR


// OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,


// ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR


// OTHER DEALINGS IN THE SOFTWARE.


//


// AUTHOR: Jonathan Bowen (www.dragondrop.uk)


// SCRIPT: Script for Airtable script block to find and replace text


// DISCLAIMER:


// - Test the script first on a copy of your base


// - Try a few different scenarios to make sure it works as you expect


// - Take a snapshot of your production base before using the script


// - Duplicate the field you're working on (with field contents) in case you want to go back to the original content


// - Use at your own risk!


Jeremy’s way:



/*


    Use this function to perform


Victoria’s way: (No Header)



let projectsTable =



Stephen’s way: (No Header)



let reportTable =

I actually use different methods, depending on the length of the script. In general, the more involved the script, the more I put in the header. If it is just a code snippet, I might omit the header.



I consider the script header comments to be an important part of the script documentation. If you have a fully fleshed out script, I recommend considering the following types of information:







  • a name for the script. Having a name for the script helps when having conversations about a script, recommending a script, referencing a script in the BuiltOnAir library, etc.







  • copyright and licensing information. This lets others know what they can legally do with the script. Since scripts are plain text, you can’t really prevent people from taking your code, but explicitly stating what you allow is still useful. The most popular opensource license for this community seems to be the MIT license. If you don’t want your script to be opensource, you should rethink whether or not you even post the script.







  • version information. This helps if you end up making different versions or revising.







  • Contact info/website. Many businesses include contact info so that potential customers who view the script can easily find them.







Also, keep in mind that some code development platforms automatically generate these headers and some auto-generated headers use particular formatting to indicate which parts are auto-generated. (e.g. only /** on the first line and only */on the last line)

What’s listed above as my “way” isn’t necessarily a guaranteed pattern that I always follow. In fact, the script from which that sample was taken is the only script I’ve shared so far, so it definitely shouldn’t be viewed as a representative example of how I’m always going to release scripts. In fact, I plan on including a header in all publicly-released scripts going forward, but not necessarily because of this thread. It’s just something I feel I should do.





I wouldn’t get too hung up on a “best” way to write a script header. You’ve obviously done some research on various headers that others have included in their scripts. Find what you feel works for you, and use it. It’ll likely morph over time, and that’s fine. Don’t get too preoccupied with trying to find the best option right away.





That’s really difficult to predict. Generally speaking, headers are designed to provide useful information to the user of the script. Some users might like to see lots of detail in a header. Others might feel a wordy/full header is unnecessary. However, I’ve never heard of someone writing a complaint letter to a script author because of a wordy header. :winking_face: That headerless example of mine above is the only time you’ll see that from me. Going forward, I plan to include a header that contains as much info as I feel might benefit the user of the script.





That’s a definite concern for some, but it partly depends on what your script does. If your script deletes records, the user should be aware of that. Then again, that may be the very reason they’re using your script, but it’s still a good idea to make sure that anyone who uses your script does so at their own risk.

Thank you so much @kuovonne , @Justin_Barrett for answering my little survey.


Your answers are detailed and very interesting, like this:





and what’s following,


and like this:





and what’s following.





Sorry I better would have written “sample” in place of “way”.





Yes I admit that in this context “near the code” or “in addition to the code”, it is a bias that I caught while having as much as possible the care to learn how to write javascript following the best patterns that you, airtable Experts, Scripters, Teachers from this Community, have kindly taken the time to share with us here.



I will follow advices from both of you.



Best,



olπ

Reply


Terms & Conditions