Naming Conventions

Typically, you spend 80% of your development time debugging, troubleshooting, and practicing general maintenance, especially on larger projects. Even when you work on small projects, you’ll spend a significant amount of time analyzing and fixing code. The readability of your code is important for your benefit and the benefit of your team members. When you follow naming conventions, you increase readability, which increases workflow and enables you to find and fix any errors in your code. All programmers follow a standardized way of writing code; this improves the project in many ways.

Using naming conventions for your variable names can serve the following important functions:

• They make your code readable so that you can immediately identify a variable’s data type. This can help students, those learning code, or developers unfamiliar with your code.
• They are easy to search for and replace when necessary.
• They help reduce conflicts with reserved words and language constructs.
• They can help you distinguish between variables from different scopes (local variables, class properties, parameters, and so on).

The following sections contain naming guidelines for writing ActionScript code, such as naming files, variables, constants, components, and so on. The section “Formatting ActionScript Syntax” discusses formatting conventions that are specific to ActionScript, and common in other programming languages. The section “ActionScript Coding Conventions” discusses coding conventions that are specific to writing ActionScript and developing with Flash 8.

Note: Flash Player 7 and 8 loosely follow the ECMAScript (ECMA-262) edition 3 language specification. It is useful to see this specification for information on how the language works.

General Naming Guidelines

This section reviews naming guidelines for writing ActionScript code. Naming conventions are important for writing logical code. The primary purpose is to improve the readability of your ActionScript 2.0 code. Remember that all variables must have unique names. Names are case-sensitive in Flash Player 7 and later. Do not use the same name with a different case, because this can be confusing to programmers reading your code and can cause problems in earlier versions of Flash that do not force case sensitivity. Keep the following guidelines in mind when you name items such as variables, files, and classes in Flash:

• Limit your use of abbreviations. Use abbreviations consistently. An abbreviation must clearly stand for only one thing. For example, the abbreviation “sec” might represent “section” and “second.”
• Concatenate words to create names. Use mixed-cases (upper and lower case) when you concatenate words to distinguish between each word for readability. For example, select myPelican rather than mypelican.
• Name a file by describing the process or item, such as addUser. Don’t use nondescriptive names for methods or variables. For example, if you retrieve a piece of data that is the visitor’s user name, you might use the getUserName() method instead of the less descriptive getData() method. This example expresses what is happening rather than how you accomplish it.
• Keep all names as short as possible. Remember to keep names descriptive.

The following sections offer more detail on naming items such as variables, classes, packages, and constants in your code.

Avoiding Reserved Words or Language Constructs

When naming instances and variables, avoid using reserved words, which can cause errors in your code. Reserved words include keywords in the ActionScript language.

Also, do not use any word in the ActionScript 2.0 languages (called a language construct) as an instance or variable name. ActionScript constructs include class names, component class names, method and property names, and interface names.

Warning: Never use different cases to avoid conflicting with reserved words. For example, naming an instance of the textfield TextField class (which doesn’t conflict with TextField because Flash is case-sensitive) is a poor coding practice.

Table 1 lists reserved keywords in ActionScript 2.0 that cause errors in your scripts when used as variable names.

Table 2 lists words that are reserved for future use in Flash, from the ECMAScript (ECMA-262) edition 4 draft language specification. Avoid using these words because they might be used in future releases of Flash.

Naming Variables

Variable names can only contain letters, numbers, and dollar signs ($). Do not begin variable names with numbers. Variables must be unique and they are case-sensitive in Flash Player 7 and later. For example, avoid the following variable names:

my/warthog = true;  // includes a slash
 my warthogs = true;  // includes a space
 my.warthogs = true; // includes a dot 
5warthogs = 55;  // begins with a number 

Use strict data typing with your variables whenever possible because it helps you in the following ways:

• Adds code completion functionality, which speeds up coding.
• Generates errors in the Output panel so you don’t have a silent failure when you compile your SWF file. These errors help you find and fix problems in your applications.

To add a data type to your variables, you must define the variable using the var keyword. In the following example, when creating a LoadVars object, you would use strict data typing:

var paramsLv:LoadVars = new LoadVars(); 

Strict data typing provides you with code completion, and ensures that the value of paramsLv contains a LoadVars object. It also ensures that the LoadVars object will not be used to store numeric or string data. Because strict typing relies on the var keyword, you cannot add strict data typing to global variables or properties within an object or array.

Note: Strict data typing does not slow down a SWF file. Type checking occurs at compile time (when the SWF file is created), not at runtime.

Use the following guidelines when you name variables in your code:

• All variables must have unique names.
• Don’t use the same variable name with different cases. Don’t use, for example, firstname and firstName as different variables in your application. Although names are case-sensitive in Flash Player 7 and later, using the same variable name with a different case can be confusing to programmers reading your code and can cause problems in earlier versions of Flash that do not force case sensitivity.
• Don’t use words that are part of the ActionScript 1.0 or 2.0 language as variable names. In particular, never use keywords as instance names, because they cause errors in your code. Don’t rely on case sensitivity to avoid conflicts and get your code to work.

• Don’t use variables that are parts of common programming constructs. Don’t use language constructs if you are aware of them in other programming languages, even if Flash does not include or support these language constructs. For example, do not use the following keywords as variables:

  textfield = "myTextField"; 
   switch = true;
   new = "funk"; 

• Always add data type annotations to your code. Also referred to as “using strict data types with your variables,” or “strong typing your variables,” adding type annotations to your variables is important in order to:

• Generate errors at compile time so your application doesn’t silently fail
• Trigger code completion
• Helps users understand your code
• Don’t overuse the Object type. Data type annotations should be precise to improve performance. Use an Object type only when there is no reasonable alternative.
• Keep variables as short as possible while retaining clarity. Make sure your variable names are descriptive, but don’t go overboard and use overly complex and long names.

• Only use single-character variable names for optimization in loops. Optionally, you can use single-character variables for temporary variables in loops (such as i, j, k, m, and n). Use these single-character variable names only for short loop indexes, or when performance optimization and speed are critical. The following example shows this usage:

  var fontArr:Array = TextField.getFontList();
   fontArr.sort();
   var i:Number;
   for (i = 0; i<fontArr.length; i++) {
      trace(fontArr[i]);
   } 

• Start variables with a lowercase letter. Names with capital first letters are reserved for classes, interfaces, and so on.
• Use mixed case for concatenated words. For example, use myFont instead of myfont.
• Don’t use acronyms and abbreviations. The exception to this rule is if acronyms or abbreviations represent the standard way to use a term (such as HTML or CFM). For commonly used acronyms, use mixed cases for improved readability, such as newHtmlParser instead of newHTMLParser.

• Use complementary pairs when you create a related set of variable names. For example, you might use complementary pairs to indicate a minimum and maximum game score, as follows:

  var minScoreNum:Number = 10; // minimum score 
  var maxScoreNum:Number = 500; // maximum score 

Naming Constants

You can use constants for situations in which you need to refer to a property whose value never changes. This helps you find typographical mistakes in your code that you might not find if you used literals. It also lets you change the value in a single place.

Variables should be lowercase or mixed-case letters; however, use the following guidelines for naming static constants (variables that do not change):

• Constants should be uppercase.
• Separate words should contain underscores.

• You can see these guidelines at work in the following ActionScript code snippet:

  var BASE_URL:String = "http://www.adobe.com";  
  // constant 
   var MAX_WIDTH:Number = 10;  
  // constant   

Do not directly code numerical constants unless the constant is 1, 0, or –1, which you might use in a for loop as a counter value.

Naming Boolean Variables

Start Boolean variables with the word “is” (because a Boolean value either “is” or “is not” because of its nature). Therefore, you might use the following for whether a baby is a girl or not (which is a Boolean value):

isGirl 

Or for a variable indicating whether a user is logged in (or not), you might use the following:

isLoggedIn 

Naming Functions and Methods

Use the following guidelines when you name functions and methods in your code.

• Use descriptive names.
• Use mixed case for concatenated words. A good example would be singLoud().
• Start function and method names with a lowercase letter.
• Describe what value is being returned in the function’s name. For example, if you are returning the name of a song title, you might name the function getCurrentSong().
• Establish a naming standard for relating similar functions. ActionScript 2.0 does not permit overloading. In the context of object-oriented programming, overloading refers to the ability to make your functions behave differently depending on which data types are passed into them.

• Name methods as verbs. You might concatenate the name, but it should contain a verb. You use verbs for most methods because they perform an operation on an object. Examples of method names include the following:

  sing();
   boogie();
   singLoud();
   danceFast(); 

Naming Classes and Objects

When you create a new class file, use the following guidelines when you name the class and ActionScript file. For proper formatting, see the following examples of class names:

class Widget; 
 class PlasticWidget; 
 class StreamingVideo; 

You might have public and private member variables in a class. The class can contain variables that you do not want users to set or access directly. Make these variables private and allow users to access the values only by using getter/setter methods.

The following guidelines apply to naming classes:

• Begin a class name with an uppercase letter.
• Write class names in mixed case when it’s a compound or concatenated word.
• Begin with an uppercase letter for a compound or concatenated word. A good example is NewMember.
• Class names are usually nouns or qualified nouns. A qualifier describes the noun or phrase. For example, instead of “member,” you might qualify the noun by using NewMember or OldMember.
• Clear names are more important than short names.
• Don’t use acronyms and abbreviations. The exception to this rule is if acronyms or abbreviations represent the standard way to use a term (such as HTML or CFM). For commonly used acronyms, use mixed cases such as NewHtmlParser instead of NewHTMLParser for improved readability.
• Use meaningful and simple names that are descriptive of the class contents. To avoid being vague or misleading, use generic names.
• Sometimes a class name is a compound word. A qualifier might describe the noun or phrase. For example, instead of “member,” you might qualify the noun using NewMember or OldMember.
• Do not pluralize the words you use in the class name (such as Witches or BaldPirates). In most cases, it is better to leave the words as qualified nouns instead. A qualifier describes the noun or phrase. For example, instead of “cat” or “buckaneer,” you might qualify the noun by using BlackCat or OldBuckaneer.
• Don’t use a class name in the properties of that class because it causes redundancy. For example, it does not make sense to have Cat.catWhiskers. Instead, Cat.whiskers is much better.
• Don’t use nouns that also might be interpreted as verbs. For example, Running, or Gardening. Using these nouns might lead to confusion with methods, states, or other application activities.
• Use unique class names for each class in a single application.
• Do not name classes so that they conflict with the names of built-in classes in Flash.
• Try to communicate the relationship that a class has within a hierarchy. This helps display a class’s relationship within an application. For example, you might have the Widget interface, and the implementation of Widget might be PlasticWidget, SteelWidget, and SmallWidget.

Naming Packages

It’s common for package names to use “reverse domain” naming convention. Examples of reverse domain names include com.adobe for adobe.com, and org.yourdomain for yourdomain.org.

• Put the prefix for a package name in all lowercase letters. For example, com, mx, or org.
• Put related classes (classes with related functionality) in the same package.
• Begin package names with a consistent prefix. For example, you might use com.adobe.projectName to maintain consistency. Another example would be com.adobe.docs.learnAS2.Users for the Learning ActionScript 2.0 book in Flash Help.
• Use a clear and self-explanatory package name. It’s important to explain the package’s responsibilities. For example, you might have a package named Pentagons, which is responsible for using the Flash drawing API to draw various kinds of pentagons in documentation examples; its name would be com.adobe.docs.as2.Pentagons
• Use mixed capitalization for compound or concatenated package names. packageName is an example of a compound, concatenated package name. Remember to use all lowercase letters for the prefix (com, org, and so on).
• Do not use underscores or dollar sign characters.

Naming Interfaces

Starting interface names with an uppercase “I” helps you distinguish an interface from a class. The following interface name, IEmployeeRecords, uses an initial uppercase letter and concatenated words with mixed case, as follows:

interface IEmployeeRecords{} 

The following conventions also apply:

• Interface names have an uppercase first letter. This is the same as class names.
• Interface names are usually adjectives. Printable is a good example.

Naming Custom Components

Component names have an uppercase first letter, and any concatenated words are written in mixed case. For example, the following default user-interface component set uses concatenated words and mixed case:

• CheckBox
• ComboBox
• DataGrid
• DateChooser
• DateField
• MenuBar
• NumericStepper
• ProgressBar
• RadioButton
• ScrollPane
• TextArea
• TextInput

Components that do not use concatenated words begin with an uppercase letter. If you develop custom components, use a naming convention to prevent naming incompatibilities with Macromedia components. The names of your components must be different from those of the default set that is included with Flash. If you adopt your own consistent naming convention, it helps you prevent naming conflicts.

Remember that the naming conventions in this section are guidelines. It is most important to use a naming scheme that works well for you and to use it consistently.