Following the rules of the code

As an application grows, the value of good code increases. Well-written ActionScript code is easier to continue developing, especially as new developers are added to the team. It is well worth the nominal extra effort to write good code. Following are some guidelines for writing superior code.

Note: Also be sure to read ActionScript 2.0 Best Practices, which will help you comment, optimize, and format your code consistently across teams to simplify debugging and maintenance.

Be strong

All variables, properties, parameters, and return values should be strongly typed. For example, rather than vaguely declaring a variable like this:

var firstName; 

the type should be explicitly assigned:

var firstName : String; 

The compiler can find more errors in code if all its elements are strongly typed, which leads to fewer disruptive runtime problems for end users. Strong typing also makes the code more readable for developers and allows code editors to provide hints and highlighting.

Be flexible

Interfaces in ActionScript define a set of functions that an implementing class must define. If your code interacts with an interface, rather than another specific concrete class that implements the interface, then the application gains flexibility. You can introduce alternate implementations of the interface later without requiring other changes to the application.

We recommend defining interfaces that isolate the aspects of the system that are likely to evolve. Using this approach minimizes the future impact of making these changes. The loading of visual and textual assets into RbkCustom is defined by a custom ILoadTask interface, which provides a simple and consistent mechanism by which we load XML and SWF files into RbkCustom.

Do that in private

All properties and functions should have an explicit scope that is private whenever possible. Maintaining private code is much easier than maintaining public code: the developer only needs to be concerned with the class itself and its subclasses.

Don’t cheat

ActionScript makes it easy to add properties and functions dynamically to an object using code like this["fu"] = "kung". However, the developer pays a high price for these shortcuts later. Because the compiler will not be able to check the validity of statements like these, typos will generate obscure runtime problems. Code editors will not be able to provide code hints on these illicitly added members either.

Defining functions on the fly causes an arcane memory leak in Flash Player because the activation object sent to the function can never be recovered by the garbage collector. So the bottom line is to avoid dynamic classes and explicitly define all the properties and functions used in your classes.

Speak clearly

Classes, functions, properties, parameters, and variables should have descriptive names. It’s worth the extra typing to bring additional clarity to more meaningful names. RbkCustom has names like SingleConfigurableProductDataParser, prerequisiteLoadGroup, and getHotPickRecipeByProductId.

Name the elements of your ActionScript code according to the accepted Java language standards. Class names start with a capital letter; other names start with a lowercase letter. For names with multiple words, all words after the first should be capitalized.

Eat your beans

Define your properties in Flash privately and provide public getter and setter functions for them. For example, RbkCustom’s User class has a private “password” property and public getPassword and setPassword functions to retrieve and assign the password. This naming matches the JavaBeans standard in Java.

We favor this encapsulated approach because it hides a class’ implementation details. We can safely and easily change the way we store the password in the User class as long as we don’t change the signatures of the getPassword and setPassword functions.

Get in line

Consistently formatted code is easier to read and maintain. Developers should agree on the usage and positioning of tabs, spaces, parentheses, and brackets. They should also agree to adhere to those conventions consistently.

We favor copious white space to facilitate scanning of the code. We place all curly braces (“{}“), looping, and conditional keywords on their own lines. We also buffer and separate the contents of parentheses by spaces. Colons are preceded and followed by spaces. For example, here’s how an IF/THEN/ELSE conditional block looks:

if ( condition )
 {
   // Code goes here... 
}
 else
 {
   // More code goes here... 
} 

And a function declaration looks like this:

private function doSomething( 
           p1 : String, p2 : Number ) : Boolean 

Write your mother

All ActionScript should be generously documented both with JavaDoc-style headers as well as free-form inline comments. Documentation inserted into the source code is most likely to be seen—and appreciated—by subsequent developers.

JavaDoc is the structured documentation style made popular in Java source code. The documentation exists in blocks that start with /** and end with */. Tags such as “@author Andrew Guldman” or “@version 1.0” can be used within JavaDoc blocks to add structure to the documentation.

Every class and function should have a JavaDoc header, as should all but the most transparently obvious properties. Here is an example of a JavaDoc function header from RbkCustom:

/**
  * Listener function called when 
 * the prerequisite data finishes loading.
  * 
  * @param ev The LoadGroupCompleteEvent 
 * broadcast to notify listeners
  * that the loading is complete. 
 */
 private function handlePrerequisiteComplete( 
              ev : LoadGroupCompleteEvent ) : Void 

Inline comments are free-form explanatory comments that explain the source code they accompany. Any tricky piece of code should include inline comments. I often write comments before I write the accompanying code to help me plan the details.

Clean your room

Developers typically experiment as they write code. Unused sections are commented out and obsolete comments abound. This situation is to be expected during development. When your code is working properly, however, you should delete these fragments. Update the comments to match the existing code and amputate the rejected code experiments.