Best Practices

[Martin Baxter]

Hi Erin,

Welcome.
Jim Ault pipped me to the "post" on this, but I have some additional 
comments in here that might help, so I send this despite some duplication.

Erin D. Smale wrote:
> Hello all,
> 
> * Functions: From what I read, a function can be called by any other 
> handler in a given script. Is it therefore best to define functions at 
> the beginning of a script, before any event handlers? If I want to open 
> a function up to the whole application, should I define it in its own 
> stack?
> 

Often, when people want to do this they will gather functions and
commands into the stack script of a "library" stack. The library stack
typically has only a stack script, and is not as a rule visible to the
user. However it may in fact also contain media such as images that need
to be globally available.

This library stack is inserted into the "message path" with the "start 
using ... " command, before you use it (it is then said to be "in use"). 
Once you don't need the library stack anymore you can remove it from the 
message path with "stop using ... " otherwise it remains open and ready 
for use.

When you Start Using a stack it is placed into the message passing 
hierarchy in such a way that its stack script becomes available to all 
open stacks. This way your library functions or commands may be used by 
any handler in any script of any open stack.

The message path is a very important concept to master.

> * Variables: I understand that vars are defined when they're initialised 
> (except globals, which need to be declared). This upsets my sense of 
> order somewhat, but I can see the advantages. That said, is it best to 
> declare variables anyway? Is there any performance impact if I do or 
> don't? Is it best practise to use the explicitVariables property?
> 

It probably is best practise, but by no means essential.

> * Variable type: The variable types are easy enough to distinguish, but 
> I'm still getting used to Transcript, so I want to make sure I'm using 
> them properly. Can someone check my work here:
> 
> (1) Local variable - accessible only within the handler that contains it 
> (declare within a handler).
>     on someHandler
>         local intValue = 5
>     end someHandler
> 

correct

> (2) Script local variable - accessible to all handlers within the script 
> that contains it (declare within a script, outside any handler).
>     local intValue
> 
>     on someHandler
>         intValue = 5
>     end someHandler
> 
>     on someOtherHandler
>         intValue = intValue * 5
>     end someOtherHandler

Your concept of scope is right but the actual syntax is wrong.
local intValue = 5
is allowed
but
intValue = 5
is never allowed. This sort of assignment is syntactically incorrect in
transcript since lines may not begin with the name of a container of
value but only with a keyword or command. So instead we write:
put 5 into intValue
and
multiply intValue by 5
or
put intValue * 5 into intValue

>   (3) Global variable - accessible to all handlers in the application 
> (declare in or out of a handler).
>     global intValue
> 
>    -- Various handlers in various scripts that manipulate intValue
> 

a global variable is accessible anywhere, but must always be declared to
give handlers explicit access to it.

If declared in a script outside of a handler, the global will be usable
by all the handlers in that script, without any further declaration.
If declared inside a handler, it is accessible to all subsequent lines
of that handler. Other handlers that might need to use it will need 
their own declaration in this case.

> I apologise for this tedious exercise in confirmation. I'm having fun 
> with Transcript, and things are working very easily, but I don't have 
> any background in HyperCard, so I want to make sure that I start out 
> with good scripting habits for use in the Rev world.
> 
> Cheers,
> 
> -- Erin

As you might expect, people here use a variety of scripting styles. 
Those who release products publicly probably have to worry about style 
more than those who only use RR for in-house tools. After the 
experimentation stage, you will gradually settle into the style that 
makes sense to you.

Martin Baxter