Guidelines for ActionScript - General Guidelines

Published:
I have been doing hardcore actionscripting for some time; and needless to say I have faced a lot of problems in just understanding others' code rather than understanding what the code executes. A programmer's life can become hell when there are a lot of developers working together in a team without a consistent framework for terminology.

Each developer uses his/her own way of coding which adds to the complexity in understanding code rather than what the code actually performs. In such scenarios, a guideline will always help a team to work without getting confused on what others have coded previously. From my experience and learning from different articles, I have tried to set up some coding guidelines for any type of ActionScript projects; these guidelines have helped me in my projects till now. The coding standard will help to streamline the Flash/Flex development structure and will lean to better performance of RIA projects. The coding guidelines should be used by any developer doing ActionScript coding.


Added to the Naming Guidelines Article, here is the list of general guidelines for any type of flash actionscripting projects.
These guidelines do not directly improve in the application performance, but definitely make the code proper, easily readable format and indirectly improves development process.

1.01    Copyright notice
Include a copyright notice at the top of every .as file in the framework. The format for the 2010 code copyright is given below.
////////////////////////////////////////////////////////////////////////////////
                      //
                      //  DOMPANY NAME
                      //  Copyright 2010 Company Limited
                      //  All Rights Reserved.
                      //
                      //  NOTICE: COMPANY permits you to use, modify, and distribute this file
                      //  in accordance with the terms of the license agreement accompanying it.
                      //
                      ////////////////////////////////////////////////////////////////////////////////

Open in new window

Note that it is 80 characters wide.


1.02    Class metadata
Organize the class metadata into sections, in the order Events, Styles, Effects, Excluded APIs, and Other Metadata.

Put a minor section header before each section. Note that the minor section headers are 40 characters wide and that there are two spaces between the // and the section name.

Alphabetize the metadata by name="..." within each section. In the Other Metadata section, alphabetize them by metadata tag name.
//--------------------------------------
                      //  Events
                      //--------------------------------------
                      /
                      **
                       *  ASDoc comment.
                       */
                      [Event
                      
                      /**
                       *  ASDoc comment.
                       */
                      [Event
                      
                      //--------------------------------------
                      //  Styles
                      //--------------------------------------
                      
                      /**
                       *  ASDoc comment.
                       */
                      [Style
                      
                      /**
                       *  ASDoc comment.
                       */
                      [Style]
                      
                      //--------------------------------------
                      //  Effects
                      //--------------------------------------
                      
                      /**
                       *  ASDoc comment.
                       */
                      [Effect
                      
                      /**
                       *  ASDoc comment.
                       */
                      [Effect]
                      
                      //--------------------------------------
                      //  Excluded APIs
                      //--------------------------------------
                      
                      [Exclude(name=“horizontalAlign”, kind=“style”)]
                      [Exclude(name=“verticalAlign”, kind=“style”)]
                      
                      //--------------------------------------
                      //  Other metadata
                      //--------------------------------------
                      
                      [DefaultBindingProperty(source=“text”, destination=“text”)]
                      [IconFile(“Text.png”)]

Open in new window



1.03    include statement for Version.as
Every class should include core/Version.as using a relative path. This file contains the declaration for static const VERSION:String.
include "../core/Version.as";

Open in new window



1.04    Indentation
Use 4-space indentation. Configure your text editor to insert spaces rather than tabs. This allows another program that uses a different indentation setting, such as Notepad with its 8-character indents, to display the code without disfiguring it.


1.05    Section separators
The major section separators inside a class look like this:
    //--------------------------------------------------------------------------
                          //
                          //  Overridden methods
                          //
                          //--------------------------------------------------------------------------

Open in new window

They extend from column 4 through column 80. The text is indented to column 8.
The minor section separators inside a class, such as between properties, look like this:
    //----------------------------------
                          //  visible
                          //----------------------------------

Open in new window

They extend from column 4 through column 40. The text is indented to column 8.
Put a single blank line above and below the separators.


1.06    Separation of declarations
Use a single blank line as a vertical separator between constant, variable, or function declarations.
/**
                       *  @private
                       *  Holds something.
                       */
                      var a:Number;
                      
                      /**
                       *  @private
                       */
                      var b:Number

Open in new window



1.06    ASDoc
Property comments
Only document the first function of a get/set function pair for a property. The idiom for defining and documenting a property is:
/**
                       *  @private
                       *  The backing variable for the property.
                       */
                      private var _someProp:Foo;
                      
                      /**
                       *  Place all comments for the property with the getter which is defined first. 
                       *  Comments should cover both get and set behavior as appropriate.
                       */
                      public function get someProp():Foo
                      {
                        ...
                      }
                       
                      /**
                       *  @private
                       */
                      public function set someProp(value:Foo):void
                      {
                        ...
                      }

Open in new window

Also, ASDoc comments are applied to metadata tags as well as other constructs within a class so take care that your comments apply to the proper target. If you tag a property as Bindable, your property comment must precede the get function, not the Bindable metadata tag.
Right usage:
[Bindable("somePropChanged")]
                      
                      /**
                       *  Comments for someProp
                       */
                      public function get someProp():Foo
                      [code]
                      
                      Wrong usage:
                      [code]
                      /**
                       * Comments for someProp
                       */
                      [Bindable("somePropChanged")]
                      public function get someProp():Foo

Open in new window



Reference Articles
http://livedocs.adobe.com/flex/2/langref/statements.html
http://livedocs.adobe.com/flex/3/html/help.html?content=asdoc_3.html
http://livedocs.adobe.com/flash/9.0/ActionScriptLangRefV3/Array.html
http://www.adobe.com/devnet/actionscript/articles/oop_as3.html
http://www.actionscript.org/resources/articles/684/1/Object-Oriented-Programming-in-AS3/Page1.html
http://oddhammer.com/actionscriptperformance/set4/
http://www.craftymind.com/2008/11/20/max-2008-session-material/
http://www.rozengain.com/blog/2007/05/01/some-actionscript-30-optimizations/
http://www.lostinactionscript.com/blog/index.php/2008/09/28/tips-on-how-to-write-efficient-as3/  
http://www.adobe.com/devnet/flex/articles/client_perf.html
http://www.stephencalenderblog.com/?p=7
http://www.gskinner.com/blog/archives/2006/06/types_in_as3_in.html
http://www.adobe.com/devnet/flashplayer/articles/resource_management.html
http://agit8.turbulent.ca/bwp/2008/08/04/flash-as3-optimization-fastest-way-to-copy-an-array/
http://blog.andre-michelle.com/2005/as3-optimations-suggestions/
http://www.ericfeminella.com/blog/2008/05/06/package-level-function-closures-in-actionscript/
http://blog.joa-ebert.com/2008/04/26/actionscript-3-optimization-techniques/
http://businessintelligence.me/projects/performance_tester/performanceTester.html
http://www.betaruce.com/blog/?p=65
1
3,444 Views

Comments (0)

Have a question about something in this article? You can receive help directly from the article author. Sign up for a free trial to get started.