One of my goals with the Pack SDK documentation is creating sample code that balances readability with being realistic. However when it comes to how parameters are passed to a formula’s execute function I’m not sure I’m living up to that ideal. Please take a look at the options below and let me know which you think would be the most helpful as you learned the platform.
Option 1: Parameter destructuring
execute: async function ([text, volume = 3, character = "!"], context) {
// ...
},
This is the pattern we currently use in the documentation. It’s succinct, but cramming so much in to one line could be hurting readability.
Option #2: Descruturing in the function
execute: async function (parameters, context) {
let [text, volume = 3, character = "!"] = parameters;
// ...
},
This options moves the destructuring down to the first line of the function. This makes it clearer than the first parameter to the execute function is all of the parameters.
Option #3: One at a time
execute: async function (parameters, context) {
let text = parameters[0];
let volume = parameters[1] ?? 3;
let character = parameters[2] ?? "!";
// ...
},
This option makes it more explicit where each parameter comes from, at the expense of it being more verbose.
Option #4: Explicit defaults
execute: async function (parameters, context) {
let text = parameters[0];
let volume = parameters[1];
if (volume == undefined) {
volume = 3;
}
let character = parameters[2];
if (character == undefined) {
character = "!";
}
// ...
},
This option removes all modern JavaScript “magic”, setting the default value for parameters in the most explicit way. This option is the most verbose however, adding 9 lines compared to the original.
Honestly, I think after seeing the four options, Option #1 still is the one I personally prefer. I will grant you that it could most likely be because it is also what I have referenced while I learned.
If I were looking for a goldilocks option, Option #2 is probably the “cleanest” example if I was just coming into it for the first time.
Option 2 is the best one for me, I would just use const instead of let. The reason why 1 is problematic is when you have many parameters but I use it when just a couple or also an empty array when no parameters.
My take is that const is good at securing your code against accidental changes once you know what you want it to do, but when you are in the messy experimentation phase it can be a bit limiting and frustrating.
option #2 is by far the best i.m.h.o.
and use ‘let’ rather than ‘const’.
i have been teaching js & python to kids in the https://coderdojo.com for some years now.
those who are new to js can get badly confused when we mix json objects into our arguments. the tiny signs like the square brackets, so clear to us, are all but invisible to newbies. so to them option#1 seems to have many arguments when it actually has only 2.
that is much clearer in option #2 while still being far more succinct than the other following options.
and ‘let’ is a simple meaningful verb whereas ‘const’ is not.
the template code used on the browser pack editor mixes declarative js code with json object definitions quite freely.
in my experience, this confuses less experienced coders.
some curly braces demark declarative blocks while some are objects within a json definition. but which is which?
a confusion of brackets, commas, colons and semicolons can overwhelm someone not used to this style of coding.
you need quite an accurate lexical analyzer running in your head when you read such code.
so any steps you take to seperate the json from the pure js syntax is a great aid to understanding on my opinion.
Thanks for the detailed feedback @Agile_Dynamics! I have also seen the mixture of syntaxes tripping up some newer coders. Any ideas on how we could avoid some of that in the Packs sample code?
As a newbie who wrote a pack as my first JavaScript code, I would definitely go for the first option.
It’s one less line of code to understand compared to the 2nd option.
I don’t mind all the signs as it’s a must learn thing in JavaScript.
It seems definitely the smoothest one, but with my dev level I have to agree with @Breno_Nunes that #1 is way more clear to understand. In #2 I would not understand how to access the variables and that some of them are default values. In #1 it is clear to me.
I’ve tried to create a pack some time ago and I felt lost faster than I thought I would (and because I don’t like that feeling, I’m currently trying to learn some JS when I’ve got the time … Strangely enough, I’m not that bad at reading it… but producing it, it’s a complete different story … I’m very slowly getting there though)
I don’t want to interfere here, as I’m at the other side of the galaxy from getting near packs but the Option 2 was still pretty understandable
Newbie here! I learn quite a bit from looking at the code with comments. Example #2 works best for me, and adding even more explanatory comments would be useful, as suggested by Max. I appreciate Eric’s efforts to make the code easy to decipher for non-coders because it will lower the barrier to entry. Also, it was not clear to me when starting with Packs that the Coda JS language was different from the JS that is taught in online courses. (My favorite course thus far has been codewithmosh.com. It’s only $15!) Going back and forth between the 2 JS versions has been a challenge.
Thanks everyone for the thoughtful feedback! I haven’t made any sweeping changes to the existing samples just yet, but I did just publish a new tutorial and went with option #2 based on your feedback:
(You made need to shift-refresh to get the latest updates to the CSS stylesheet.)
Give it a read and let me know if this “unpacking” metaphor makes sense. Any other feedback welcome as well, as I plan to create more tutorials using this format.
Your formula tutorial is fantastic! What a great idea to start with the simple structure (scaffolding) and then adding some minimal complexity, step-by-step, with testing. Also, the links to the JavaScript.info tutorial are useful to supplement and add context to your instructions. Would you consider adding the simple code for a column format as an additional step, or would that add to much complexity? (It took me a while to figure out that the column format code and formula code could be included in the same build.) More tutorials like this one will be super useful!
Thanks for the feedback @Lynn_vK! I think that tutorial is already a bit long, but I’ll add a TODO to create a tutorial for column formats, perhaps building off of that code.
@Scott_Collier-Weir - Not at all! All four of the options in the original post work now and will continue to work. I’m just trying to figure out how best to demonstrate these concepts in the docs.
I’m in the #2 camp too (maybe #1, but #1 is pretty heavy on the magic).
It’s hard to get around an underlying ambiguity which is that, while your destructured variable names will often match your parameter names, in truth that’s entirely coincidental; all that matters is their position in the parameters array. I can see that tripping folks up when they add/remove or reorder parameters. But I think making it explicit with the array references in #3/#4, results in an intimidating wall of code that’s not worth it.
This 
(and because I don’t like that feeling, I’m currently trying to learn some JS when I’ve got the time 
… Strangely enough, I’m not that bad at reading it… but producing it, it’s a complete different story 
