The main cost of Drafts script actions at the moment is the rather slow (and slightly feed-back impoverished) cycle of testing and adjusting:
Several levels of tapping to select and edit a script action, then
ditto to read any console.log or error output, and
often limited or absent error information.
An important culprit here is the use of the older var rather than the more current let.
Among other advantages, the newer let gives a beginner helpful error information, where the old legacy var gives none.
Imagine, for example, that we accidentally reuse a variable name.
var a = '123e4567-e89b-12d3-a456-426655440000';
// then, somewhere lower down ...
var a = 42; // We've now lost the UUID, but we get no warning or explanation at all
var just destroys the value in the first assignment, and gives us no warning of what has happened.
let is very much more helpful:
it triggers a red ‘!!’ warning in the code editor, as soon as we make the mistake, and
if we run the code, it gives us an explanatory error message, with line number:
SyntaxError: Cannot declare a let variable twice: "a"
Line number: 9
let a = "123e4567-e89b-12d3-a456-426655440000";
// then, somewhere lower down ...
// We get an instant red !! warning in the editor if we now type this:
let a = 42;
// and an explanatory error message with line number if we run it.
@agiletortoise I’m not sure whether the use of var in the API documentation examples is a legacy thing (compatibility with an earlier Drafts/JS ?) but perhaps it would be helpful to do a (var -> let) search replace ? It would allow beginners to immediately get more help from the Drafts code editor, and from the error panel.
(In nearly all the examples, const would, of course also work, and might have advantages (we can declare an object as a const, and still update its properties – we just can’t change the reference to a different object), but perhaps simpler for beginners not to have to deal with that choice too soon ?)
const is the ideal default (executes faster, encourages avoidance of unnecessary mutation)
let is needed for any real mutation (not needed for any object property updates)
Both give helpful error messages, and editor warnings, where var gives nothing at all, and just leaves us in the dark.
Good tips. Generally speaking, using the latest features of a language are nice and offer some benefits, but aren’t the best way to provide examples, because they make it look alien to people looking at common example and tutorials on the web, so I try to avoid those features in code examples.
Your tips and tricks have been great for advanced users, but to a novice things like Array reduce are scary and harder to read. Similarly, sprinkling an example with optimized uses of var, let and const tend to make it less approachable to the non-programmer because they are faced with another set of concepts that make them feel like the are doing it wrong if they don’t understand the nuances differentiating them when a plain old var would just work fine.
For the most part, in the types of simple scripts people are writing in Drafts, the performance differences are negligible.
Performance differences are certainly negligible – JSC is unlikely to be the bottle-neck anyway in running an action.
I’m not sure, though, that the friction and the time-consumption in the test -> read message -> re-edit cyle are really negligible at all at the moment, and it seems a pity to deprive beginners of helpful error messages …
But you have your reasons – I just wanted to check that the use of var was deliberate – sounds like it was.
Perhaps we can just agree to disagree on that one
( Where you write “plain old var”, I think we might do better to substitute “plain old let”, but the stakes are not high – just a bit more time wasted in confusion and debugging – and you seem to feel that that’s a price worth paying for congruence with older teaching resources … despite the clash with newer teaching resources ? )
As long as people know that they will get more help from let (and const), the influence of the documentation examples shouldn’t be too disabling.
sprinkling with optimised use of var, let and const
new set of concepts
Perhaps slightly misleading formulations there ?
There’s no longer any need for var, so the most complex choice would only ever be between const and let
As for new set of concepts – in fact just one – the distinction between mutable and not.
That’s a concept which your documentation examples have already introduced – in some of them you already have both const and var.
In reality, no new concepts at all, and no new choices at all, are introduced by using let as the new (more informative, and more user-friendly) replacement for var
At the same time, anyone who googles for “JavaScript for X problem” for example would likely end up on StackOverflow or similar, and the examples there usually have var vs let or const. It all depends on how the beginner starts, if they start with a book that’s fine, but people often start by looking for solutions to specific problems.
The point, however, is that the cost / advantage balance simply fails if the main advantage is ‘compatibility with learning materials’.
Older materials use var, newer materials use let. In other words there is a compatibility cost in either direction, and with time the use of var will only get more costly and confusing in these terms.
That leaves us with just the utility value of let vs var.
let has a simpler and more intelligible behaviour, and provides both editor warnings and run-time explanations.
var has confusing properties, and offers no editor warnings or run-time explanations.
( as for the web-search argument – the Drafts 5 wiki and advertising materials specify the JS flavour used as ES6 – a beginner who sensibly searches for any variant of “ES6 Javascript” will find not just more let than var but also clear cautions against using var )
I would argue that someone not familiar with programming would not realise that ES6 is important, especially considering how often I see people at that level confuse Java and JavaScript. That’s not to say that correct terminology isn’t important, but looking at what beginners do and are likely to do is also very useful
But as I said, the compatibility with materials argument goes both ways, its just a choice between being incompatible with newer materials and incompatible with older materials.
That leaves us with just the question of which of the two is genuinely more helpful and less time-wasting for beginners.
Neither of you has disputed that let is simpler and more helpful to beginners than var
I have no interest in an argument about programming best practices. As far as I’m concerned, for the purposes of productivity automation, if it does what you want it to do than it’s well programmed.
I think it’s great you are offering useful tips for making more reliable and modern Javascript, please keep it up. Just keep the tone friendly. It can very quickly turn, intentionally or not, from being helpful to making people feel like they are being told they are doing it wrong.
The majority of the people experimenting with Javascript in Drafts are not programmers, just novices trying to make their lives a little easier.
Absolutely, and ditto – I’m not a programmer either, which may help me empathise a bit more with the predicament of other non-programmers, who, like me, need what is simpler more than we need what is more traditional.
Out of curiosity, if one were to take the techniques you keep advocating and use them in a more conventional JavaScript setting, I.e. in a web page, would most browsers be able to run them?
On this point, I instead found this advice: “ I do not advise doing a global search and replace for your var declarations because I bet you will see many scope related exceptions pop-up!” here
(All of the major desktop browsers have caught up with const and let)
Precisely because var has some different and peculiar properties, and it’s not impossible to inadvertently create code which depends on leaky or eccentric scoping, I certainly wouldn’t generally recommend global search and replace for arbitrary sets of code. It just happens to be feasible for Greg’s set of documentation examples.
But if you are writing fresh code, sticking to let and const will allow the editor and interpreter to flag up problems that slipped through unnoticed with var.
Picking up on one of the themes of this thread, anything that can reduce interactions / time when editing and testing javascript actions would be good.
One simple example: A button to immediately edit the javascript in a single-step action and another to immediately return to the draft would help with javascript development.
I say “single step” as I, for one, have quite a few of those. Plus there is no “which step?” ambiguity in that case.
I agree fewer interactions would be better. However, for writing and managing my actions, I now use a script that sources the JS from a specific Draft UUID and uses eval() to run it. I don’t really notice a speed difference. It also lets me use library scripts that are included in the final execution.
Someday I’d love to be able to edit the scripts in a proper code editor like Textastic. With my Python scripts I am able to open them in Pythonista, Working Copy, or Textastic – all without moving any files or doing any copy/paste. It’s so cool!
