The main takeaway I have is that coders are going to be talking to their new IDEs, maybe sometimes loudly but most of the time in thanks, and that is a good thing. This was written in early December 2020:
With the new IDE for AppsScripts, that platform has completed what you might think of as a nearly complete overhaul. It came in two stages, (with hopefully a third one around the corner, but not the focus of this essay).
- Months ago: The new V8 engine, giving it a modern runtime environment, and cool new syntax features
- This week: A new IDE, which gives us a proper logger and a dependable debugger, and makes finding easy-to-fix programming mistakes a cinch
The first step gave us modern JavaScript and all the feature sets that programmers can rely upon, and now the second step gives it an environment that will let programmers really tap into the language.
Up to now, I have often observed that AppsScripting has been about automation and integrations, and not so much that it's about using JavaScript and loving the language as a language.
Now we're able to really dig into things. And that's pretty exciting!
The first thing that jumps out at you when using the new editor is how verbose it is. When you type a function it starts popping up with code hints about what the first parameter is supposed to be.
Scene:
Coder: Oh, so the first parameter is type
Number?
IDE: Yes
Coder: Types the variable name
num
IDE: That variable is not actually a
Number, and I will show that to you by using red squiggles underneath the variable. Here you go.
The coder stops in their tracks
Coder: It's not a number? Yes it is!
IDE: I don't get stuff like this wrong, you know.
Coder: But how is it not a number?
The coder is confused, and momentarily opens his mouth to perhaps drop a mildly honest comment about the state of computing in the world. He is stopped in his tracks, however, when he types:
Logger.log(typeof num);And is pleasantly rewarded by the Execution Log which reports to him that in fact
numis aString, which of course it is because coder overlooked something.Coder: I just learned something.
IDE: That's the idea.
A verbose IDE is a good thing, but there's a lot to get used to here. A coder might have a legacy project they have been working on forever and suddenly they have red squiggly lines all over the place. Surely the coder knows what he has been doing, and gosh darn it it works!
The IDE can only work with what it's got, and it's not going to make sense. It's not going to be wrong per se, but it's not going to make a lot of sense at once.
I mean, the autocomplete lets you instantly remember what sort of methods you can call on a String or Number or Arrray. That will save you so much time, and let you know what kind of thing it is before even executing the code.
It can be daunting. However, the transition will be worth it.
So how does the IDE do that? How does it know what types the variables are, and in addition what methods they have? The answer is that it's documented.
Someone wrote the documentation, and that needs to be done in a formal, reproducable way, just like coding. In fact, in a way jsdoc is like a metalanguage describing the coding language.
So all of these variables and methods are documented. And you know what, the ones you write should be, too, and the reward for that will be a better IDE.
Scene:
Coder: Oh wow, so this method returns an array of strings.
IDE: Yes
Coder And so when I assign a variable to the returned value, I have all the array methods autocompleting for me.
IDE: Yes
Coder: I'm using this other function now, but I don't get the autocomplete. Maybe there's a bug?
IDE: Please document your function
Get used to spending more time learning the ins-and-outs of jsdoc, that lovely language that describes how your variables interplay with the other variables. (The best resource for that is stackoverflow. Don't bother with the formal specification, go by examples in the wild.)
It's fun to learn. For this particular gist, I learned how to document a function that takes an unlimited amount of parameters, that can be anything at all.
The part that I learned is the {...*} params bit.
And here are the fruits of my labors:
/**
* Converts all of the parameters passed to it to strings and returns them as an array
* @param {...*} params
* @returns {String[]}
*/
function myFunction(...params) {
return params.map(p => p.toString());
}
function testMyFunction() {
const numbers = myFunction(1, 2, 3);
const anything = myFunction('sdkjs', 11, [1, 2]);
}Try it yourself. Check out how the numbers variable knows it's an array of strings, and how when you type myFunction it's telling you all you need to know about the special function you just wrote.
I like writing esoteric bits of code like above, but you don't have to. Keep it plain and simple, ain't nothing wrong with that. AppsScripts is a platform for the practical, not really intended to be a Computer Science haven of the latest and greatest amazeballs tech.
But there's something that coders all know and should do, no matter where on the imagined pyramid you may think of yourself as being on, is that they are writers, and writers have to write expressively and clearly.
What better motivation to do that than to have it be pointed out that three months from now, you're going to take a look at your own code, and have absolutely no idea what it does. I WILL happen.
Take a look at that esoteric code I wrote above. Maybe that .map function is throwing you for a loop, and/or what are the three ... doing in the function signature? These are learnable things, but the point of the documentation is that you don't have to to understand what is going on here.
It's future self proof.
If it's future self proof, then it's better writing.
Happy conversations.