----- Original Message -----
From: "James Newton" <james.newton@...>
>
> > - Do not comment indvidual lines or chunks of code unless absolutely
> > necessary. In such cases, explain *why* the code is written the way it
is,
> > not *what* the code does, unless it really is not obvious what the code
is
> > doing by looking at it.
>
> There are times when I would want to comment the *what* of an individual
> line of code. For example, an Undo script may need to do several things,
> such as altering a data structure, updating an interface in a MIAW and
> updating an interface on the Stage. Each of these operations would need a
> comment to distinguish it from the others, even if the operation itself
only
> required a single line of code.

Bear in mind that these are only *guidelines* not hard-and-fast rules (which
the naming conventions pretty much are). They are just a guide to writing
good code. There are of course, exceptions. Rather than try to list all the
exceptions it's better to just leave it up to the good judegement of the
programmer to know when something makes sense. In a more complete writeup
I'd probably stress the flexibility of the above a bit more, but the good
thing about putting it that way is that it makes people _think_ about their
comments a bit more, and avoid over-commenting.

> > The openLingo naming convention is:
> >
> > - Names are always first-letter caps with the first word (or prefix)
being
> > all lowercase. Only exception is private globals...
> > - Private globals begin with a double underscore and words are all
> > lowercase, separated by underscores, e.g., __global_controller
>
> Excuse my ignorance, but what is a "private global"?

Well there is no such thing as a private anything in Lingo. However, the
concept of a private global is similar to a static variable in C, where the
variable should be local to a specific package or collection of packages,
but it simply isn't possible to create such a thing in Lingo.

In fact, it is possible to create static variables but they are very slow to
access, so not ideal if you need to access them frequently. Also, this still
wouldn't make them any more private than a global variable, so there isn't
much point.

Basically with the openLingo naming convention, if something has an
underscore at the start of it's name you need to think twice before directly
accessing it - the chances are it doesn't belong to you, and there will
always be an alternative interface provided.

The openLingo wrapper script contains one "private" global called
__ol_singleton. No-one should ever access this variable. It is used in the
wrapper scripts, but those scripts are the only ones that should ever touch
that variable. If anyone else wants to do anything with that variable, it
should be done via the interface provided.

- Robert