----- Original Message -----
From: "James Newton" <james.newton@...>
>
> I'm new to this list, so perhaps there are reasons for working in the
> approved way that I am not aware of. My reasons for the changes are
> connected with debugging:
>
> * If the "if ... then" statement is on the same line as the action it
> generates, step by step debugging will not show whether the line is
> executed or not
> * If the result is calculated on the same line as it is returned,
> you may not be able to see what value *is* returned, either in the
> current handler or in the calling handler.

Not really, these points were never brought up before, so it was never a
criteria for whether something should be approved or not. As far as making
debugging easier is concerned, these are good points that I wouldn't have
noticed myself because I don't use the debugger. Ever.

I'd be happy enough to add these changes to the conventions and update any
approved code accordingly. Suggestions such as these are always welcome -
it's kinda the whole point of openLingo.

> * The "me." prefix is unnecessary for properties declared in the
> current script. It is only required if the property is declared
> in an ancestor. I omit the "me." where possible, so that it is
> clear when a property is "personal" or "inherited".

The reason for the me prefix (and this *was* discussed at length) is because
of the way inheritance works in Lingo. If you override a property in a
descendant object and then call a handler in the ancestor then:

val = pProperty -- the value set locally
val = me.pProperty -- the "real" value, set in the descendant

It is therefore mandated that all openLingo scripts use me.xxxx to refer to
properties so that those properties can be overridden in descendant objects
while maintaining the correct behaviour. It's not a big deal, and it also
makes the code very marginally slower, but these rules are supposed to make
the code easier to expand later, if/when the library becomes much more
complex in the future.

BTW, I did a complete set of tests relating to this, which are here:
http://www.killingmoon.com/director/tests/inheritance/

> (The "t" prefix for temporary variables follows the practice used in the
> more recent Director behaviors, which also use a "p" prefix for
properties).

The openLingo convention for a local variable is to use the prefix "v" (for
"variable").

I wrote a short summary of the openLingo conventions in a recent post on
m.d.l - it's probably not as complete as a full writeup, but since the basic
philosophy of openLingo is to have a fairly simple and not overly-strict set
of conventions anyway, it's probably not a bad summary. Here it is:

Some general guidelines for code style:

- Try to keep functions short (one page max), break complex things down into
smaller chunks, but make each function general purpose. Give functions
meaningful names that say what the function does (the name should be or
include a verb). If a function must be longer than ideal, try to split it
into sub-chunks with a short comment to say what each part does.

- Give variables meaningful names. Don't use x, y, i, j, except in short
loops or places where it is absolutely obvious what they mean.

- Comment files and functions. Explain what the file is, who has worked on
it, etc. Say what each function does, what the inputs and outputs are, etc.

- 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.

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 (see below).
- Functions are verbs (says what the function *does*)
- Object instances / variables are nouns (says what the variable *is*).
- Properties start with lowercase "p", e.g., pMyVariable
- Globals start with lowercase "g", e.g., gMyGlobal
- Function arguments (except "me") start with a lowercase "a", e.g., on
doStuff me, aTarget
- Local variables start with a lowercase "v", e.g., vLocH
- Private properties begin with an underscore, e.g., _dontTouchThis
- Private globals begin with a double underscore and words are all
lowercase, separated by underscores, e.g., __global_controller

- Robert