Javascript discussion: Variable scopes and functions

Question

Hi,
I'm wondering how people proceed regarding variable scope, and calling
functions and things. For instance, it's finally sunk in that almost
always a variable should be declared with var to keep it local.
But along similar lines, how should one deal with functions? That is,
should every function be completely self contained -- i.e. must any
variables outside the scope of the function be passed to the function,
and the function may not alter any variables but those that are local to
it? Or is that not necessary to be so strict?
Functions also seem to be limited in that they can only return a single
variable. But what if I want to create a function that alters a bunch of
variables?
So I guess that's two questions:
(1) Should all functions be self-contained?
(2) What if the function needs to return a whole bunch of variables?
Thanks,
Ariel

Answer 1

Ariel:
(Incidentally, I couldn't find any way of  marking answers correct when I visited the web forums a few days ago, so I gave up.)
It's there...as long as you're logged in at least, and are the poster of the thread.
What I want is to write code that I can easily come back to a few months later
and make changes/add features -- so it's only me that sees the code, but
after long intervals it can almost be as though someone else has written
it! So I was wondering if I would be doing myself a favour by being more
strict about make functions independent etc. Also, I was noticing that
in the sample scripts that accompany InDesign (written by Olav Kvern?)
the functions seem always to require all variables to be passed to it.
Where it is not impractical to do so, you should make functions independent and reusable. But there are plenty of cases where it is impractical, or at least very annoying to do so.
The sample scripts for InDesign are written to be in parallel between three different languages, and have a certain lowest-common-denominator effect. They also make use of some practices I would consider Not Very Good. I would not recommend them as an example for how to learn to write a large Javascript project.
I'm not 100% sure what you mean by persistent session. Most of my
scripts are run once and then quit. However, some do create a modeless
dialog (ie where you can interface with the UI while running it), which
is the only time I need to use #targetengine.
Any script that specifies a #targetengine other than "main" is in a persistent session. It means that variables (and functions) will persist from script invokation to invokation. If you have two scripts that run in #targetengine session, for instance, because of their user interfaces, they can have conficting global variables. (Some people will suggest you should give each script its own #targetengine. I am not convinced this is a good idea, but my reasons against it are mostly speculation about performance and memory issues, which are things I will later tell you to not worry about.)
But I think you've answered one of my questions when you say that the
thing to avoid is the "v1" scope. Although I don't really see what the
problem is in the context of InDesign scripting (unless someone else is
going to using your script as function in one of theirs). Probably in
Web design it's more of an issue, because a web page could be running
several scripts at the same time?
It's more of an issue in web browsers, certainly (which I have ~no experience writing complex Javascript for, by the way), but it matters in ID, too. See above. It also complicates code reuse across projects.
Regarding functions altering variables: for example, I have a catalog
script. myMasterPage is a variable that keeps track of which masterpage
is being used. A function addPage() will add a page, but will need to
update myMasterPage because many other functions in the script refer to
that. However, addPage() also needs to update the total page count
variable, the database-line-number-index-variable and several others,
which are all used in most other functions. It seems laborious and
unnecessary to pass them all to each function, then have the function
alter them and return an array that would then need to be deciphered and
applied back to the main variables. So in such a case I let the function
alter these "global" (though not v1) variables. You're saying that's okay.
Yes, that is OK. It's not a good idea to call that scope "global," though, since you'll promote confusion. You could call it...outer function scope, maybe? Not sure; that assumes addPage() is nested within some other function whose scope is containing myMasterPage.
It is definitely true that you should not individually pass them to the function and return them as an array and reassign them to the outer function's variables.
I think it is OK for addPage() to change them, yes.
Another approach would be something like:
(function() {
  var MPstate = {
    totalPages: 0,
    dbline: -1
  function addPage(state) {
    state.totalPages++;
    state.dbline=0;
    return state;
  MPstate = addPage(MPstate);
I don't think this is a particularly good approach, though. It is clunky and also doesn't permit an easy way for addPage() to return success or failure.
Of course it could instead do something like:
    return { success: true, state: state };
  var returnVal = addPage(MPstate);
  if (returnVal.success) { MPstate = returnVal.state; }
but that's not very comforting either. Letting addPage() access it's parent functions variables works much much better, as you surmised.
However, the down-side is that intuitively I feel this makes the script
more "messy" -- less legible and professional. (On the other hand, I
recall reading that passing a lot of variables to functions comes with a
performance penalty.)
I think that as long as you sufficiently clearly comment your code it is fine.
Remember this sort of thing is part-and-parcel for a language that has classes and method functions inside those classes (e.g. Java, Python, ActionScript3, C++, etc.). It's totally reasonable for a class to define a bunch of variables that are scoped to that class and then implement a bunch of methods to modify those class variables. You should not sweat it.
Passing lots of variables to functions does not incur any meaningful performance penalty at the level you should be worrying about. Premature optimization is almost always a bad idea. On the other hand, you should avoid doing so for a different reason -- it is hard to read and confusing to remember when the number of arguments to something is more than three or so. For instance, compare:
addPage("iv", 3, "The rain in spain", 4, loremIpsumText);
addPage({ name: "iv", insertAfter: 3, headingText: "The rain in spain",
  numberColumns: 4, bodyText: loremIpsumText});
The latter is more verbose, but immensely more readable. And the order of parameters no longer matters.
You should, in general, use Objects in this way when the number of parameters exceeds about three.
I knew a function could return an array. I'll have to read up on it
returing an object. (I mean, I guess I intuitively knew that too -- I'm
sure I've had functions return textFrames or what-have-you),
Remember that in Javascript, when we say Object we mean something like an associative array or dictionary in other languages. An arbitrary set of name/value pairs. This is confusing because it also means other kinds of objects, like DOM objects (textFrames, etc.), which are technically Javascript Objects too, because everything inherits from Object.prototype. But...that's not what I mean.
So yes, read up on Objects. They are incredibly handy.