Below is a work in progress from a few years ago.
I used it for an AppleScript class I was teaching and I think it
helped.
It is not complete and may need to be updated.
This was inspired by a similar document for Hypertalk, and is based,
in
part, on an open-source guideline for scripting. The title comes
from the
writing guide "Elements of Style."
Please feel free to comment, critique or offer suggestions.
ES
ELEMENTS OF APPLESCRIPT STYLE
Abstract
AppleScript is the scripting language developed by Apple Inc. to
facilitate
interapplication communication Macintosh Computers. Originally
developed for
Mac OS7, it is now part of Mac OS X 10.x.
This style guide for writing scripts using AppleScript is designed
to help
users create scripts that best take advantage of AppleScript's
"English-like
syntax."
Keywords: scripting, AppleScript.
Contents:
Introduction
General AppleScripting Discussion
Comments in AppleScript
Variable and Handler Names
Variable Labels
Single Character Variable Names
"The" in Variable Lablels
Handler Labels
General AppleScript Guidance
Parens
Object Names
Using Properties and Globals
Introduction
Scripts written in AppleScript are referred to as AppleScripts.
AppleScripts
can come in many forms and be used for a wide variety of tasks. As the
scripting language matures develop and AppleScripters form
communities and
begin to reuse, repurpose and share AppleScripts, this style guide
will
provide a common format for easily understood scripts.
General AppleScripting Discussion
AppleScript is the term used for both the AppleScript scripting
language and
the AppleScript technology and interapplication communication
environment
found in Apple Macintosh computers running Mac System 7.1 through
9.x and in
Mac OS X 10.x.
An AppleScript is a script written in the AppleScript language to
run in the
AppleScript environment. The contents of the script may also be
referred to
as AppleScript.
The term "code" should be avoided when referring to AppleScripts. A
code, by
definition, is a form of communication designed to be understood by
a select
group. A well written AppleScript should be easily understood by most
computer users.
An AppleScript "Applet" is an AppleScript that can be run as a stand-
alone
application.
An AppleScript "Droplet" is an AppleScript Applet that will respond
when
icons are dragged onto and dropped on its Icon. To do this, an "open
handler" must be included in the script.
---------
on open fileList
--your appleScript commands go here
end open
---------
Comments in AppleScript
Scripting and program languages often use comments to describe the
purpose
and funcion of specific lines of script or code, particularly when the
meaning may be obfuscated by the limitations of the language.
A clear, well written AppleScript should be able to convey its
meaning with
little or no commenting. Often a well written AppleScript reads like a
comment in another application.
Comments in AppleScript should be used sparingly, only when necessary.
A comment to introduce and separate part AppleScript that handles a
specific
function, when that is not clear is acceptable
Examples:
---------
-- The user selects the primary label
set userChoice to display dialog "How would you like to label this
information?" buttons {"Hot", "Warm", "Cool"} default button 1
giving up
after 30
set labelChosen to button returned of the selection
if gave up of user choice is true then then set scriptMode to
automaticMode
---------
---------
-- The tip calculation
if serviceLevel is "outstanding" then
set tipPercent to 20
else
set tipPercent to 20
end if
set tipAmount to billTotal mod tipPercent
---------
--A comment may clarify a command whose meaning is not self-evident
in the
script
Examples:
-- <TK>
-- A comment may identify problem areas in an AppleScript which may
speed
debugging or editing
Examples:
-- <TK>
Comment Effectively
As a general rule, only comment any block of AppleScript whose
functionality
is not immediately self-evident. For example, it's merely
distracting to
see:
----------
-- Change the cursor to watch
set the cursor to watch
----------
But it's very helpful to have a brief note like this for more complex
blocks:
----------
-- Update record with the date:
set the cursor to watch
put the current date into todaysDate
repeat with i = 1 to the number of cds
put todaysDate into folder "Date" of cd i
end repeat
----------
Comments can also be used as visual guides, separating different
sections of
AppleScript. Here's an example of how sets of related handlers can be
grouped visually using commented lines:
-- <TK>
Comments may also be used at the top or the bottom of a script to
convey
information about the the script:
----------
--AppleScript Language Guide
--July 18, 2007
----------
Variable and Handler Names
Variable Labels
Variable labels should be descriptive of their contents.
Variables labels may be compound nouns that consist of two or more
words
merged into a single word, with capitalization marking the beginning
of the
second and subsequent words. The first letter of variable labels
should be
lowercase (to distinguish from handlers)
Variable labels examples:
userDocument
thisItem
myPage
fileInUse
userChoice
userPassword
Avoid using the underscore character to separate words in variables.
They
make the script harder to read, and, in some AppleScript editors,
cannot be
selected with a double click.
Single Character Variable Names
The exception to the previous rule is counters which serve no other
function
except as an index within a loop. Traditionally, counters begin with
the
variable "i" and procede through the alphabet (next use "j," then
"k," then
"l."). You can also use x, y, z or a,b,c in the same manner.
Single character variable names may be used for integers inside repeat
loops.
---------
repeat with x from 1 to 100
repeat with y from 10 to 1
set z to 1
repeat until z > 10
set z to z + 1
end repeat
end repeat
end repeat
---------
x, y, z, i, a, b, c are the most commonly used single character
integer
variable labels.
If using a single character variable label for integers adds any
confusion a
more descriptive term should be used.
"The" in Variable Lablels
Do not use the article "the" as a variable part:
AppleScript allows the script writer to insert the word "the" into the
script to improve the readability.
the userDocument
the fileInUse
Using "the" as part of a variable name makes the script less readable.
Note, this does not prohibit "the" when it's part of an word used as a
variable label.
theatreShowTime
studentTheme
Are perfectly acceptable.
theTheatreShowTime
theStudentTheme
Are discouraged.
Examples of variable naming style to avoid:
theUserDocument
thePage
theFileInUse
user_document
this_item
my_page
file_In_Use
user_Choice
user_Password
Handler Labels
Handler names should follow the same syntax used for variable names.
Descriptive compound words.
The first character in a handler name should be uppercase, to
distinguish
from variable names.
A handler's name should be descriptive of its function.
Do not use "Get" in a handler name.
The get command in AppleScript can be applied to handlers, and it it
used in
the handler command may create awkward syntax:
get GetFinderSection()
get FinderSelection()
Clarify Program Flow
One way to prevent overly complex and convoluted scripts is to make
sure
your script's logic is self-evident. For example, if you have one long
handler which takes care of a variety of startup tasks, you could
break that
down into multiple handlers which handle only specific related
tasks. If you
use descriptive names, you'll have no trouble grasping how the main
handler
and each called handler function:
--------------
on StartUp()
InitiatePreferences()
UserData()
CreateWindows()
end StartUp
--------------
The time required by to handle separate calls is insigificant, and
isolating
specific sets of related routines in this way can help the script
writer
track down the source of errors during debugging.
AppleScript Handlers for Reuse
As you write your AppleScripts, always think if may use a particular
set of
commands in other scripts. If so, break them out into a separate
handler so
you can save it to a library and use it over and over.
Similarly, if you see yourself typing the same lines into a new
handler that
you used earlier in another, maybe that's a good opportunity to
break it out
as a separate handler to be called from both.
When you write your handlers, try to make them as generalized as
possible.
Another way to keep AppleScript portable is to remove references to
specific
objects. If you have a function which calculates the sum of two
fields for
example, a non-portable version might look like this:
--------------
put SumFields()
on SumFields ()
tell appliction "MyDataBase"
return field "Num1" + field "Num2" + field "Num3"
end tell
end SumFields
--------------
This handler only works if you have three fields using those
specific names.
You could make it more portable like this:
--------------
get SumFields({field "Num1", field "Num2", field "Num3"})
on SumFields (fieldList)
put 0 into sumOfFields
repeat with i = 1 to paramcount()
set sumOfFields to sumOfFields + item i of fieldList
end repeat
return sumOfFields
end SumFields
--------------
General AppleScript Guidelines
Parens
Parentheses can be used (and are sometimes necessary) to group
logical or
arithmetic expressions or to clarify AppleScript:
if (the visible of window myWindow) then
instead of:
if the visible of window myWindow then
Object Names
When referring to applications' objects, use names whenever
possible. If the
name cannot be known or may change, use the object's ID number (if
possible). Try to avoid using the ordinal number of the object (e.g.,
"paragraph 4"), as changes to the document may will cause the script
to
break. Descriptive names also help you understand the purpose of the
object.
Using Properties and Globals
Use globals appropriately, keeping in mind AppleScript globals do
not have
the same scope as globals in other languages. An AppleScript
global's scope
is limited to the script itself and script objects it spawns and
script
objects that spawned it.
Globals should be declared in the first line(s) any handler they are
used
in. They can be declared in the first line(s) of your AppleScript
as well.
Declare all properties in the first line(s) of your AppleScript.
_______________________________________________
Do not post admin requests to the list. They will be ignored.
AppleScript-Users mailing list (applescript-
email@hidden)
Help/Unsubscribe/Update your Subscription:
Archives: http://lists.apple.com/archives/applescript-users
This email sent to email@hidden