AS3编码轨范2

2012-06-28

AS3编码规范2Flex SDK 编码规范及最佳实践（资料共享）注意:本文档目前还不完整且有些部分以TBD(待讨论)标记

AS3编码规范2

Flex SDK 编码规范及最佳实践

（资料共享）

注意:本文档目前还不完整且有些部分以TBD(待讨论)标记, 但这对于起步已经足够了!

引言

这篇文档拟定了用AS3编写开源Flex框架组件的编码规范. 遵照这些规范可以使得源代码看起来组织良好,风格一致并且更加专业.其中有些规范是很任意的,因为并非总存在一种”最好方式”来编码. 然而,为了照顾一致性的要求,所有付诸Flex SDK的项目都将遵循这些编码规范.

命名

·????????缩写词

·????????缩略语

·????????单词定界

·????????类型指定名

·????????包名

·????????文件名

·????????命名空间名

·????????接口名

·????????类名

·????????事件名

·????????样式名

·????????字符串属性枚举值

·????????常量名

·????????属性 (变量和getter/setter) 名

·????????存储变量名

·????????方法名

·????????事件处理方法名

·????????参数名

·????????资源包名

·????????资源键名

·????????杂项名

语言用法

·????????编译选项

·????????基于属性的 APIs

·????????类型定义

·????????Literals

·????????Expressions

·????????Statements

·????????Declarations

文件组织

·????????Copyright notice

·????????packagestatement

·????????importstatements

·????????use namespacestatement

·????????Class metadata

·????????Classdeclaration

·????????includestatement for Version.as

·????????Implementationnotes

·????????Classinitialization

·????????Class constants

·????????Class mix-ins

·????????Class resources

·????????Class variables

·????????Class properties

·????????Class methods

·????????Constructor

·????????Variables

·????????Overriddenproperties

·????????Properties

·????????Overriddenmethods

·????????Methods

·????????Overridden eventhandlers

·????????Event handlers

·????????Out-of-packagehelper classes

格式化

·????????Line width

·????????Indentation

·????????Sectionseparators

·????????Separation ofdeclarations

·????????Metadata

·????????Array indexing

·????????Commas

·????????Array literals

·????????Object literals

·????????Functionliterals

·????????Typedeclarations

·????????Operators andassignments

·????????Statements

·????????Constant andvariable declarations

·????????Functiondeclarations

·????????Function calls

·????????if statements

·????????for statements

·????????switchstatements

·????????class andinterface declarations

ASDoc文档

·????????Propertycomments

命名

编码时采用合适的命名既便于使用且理解起来也更为容易.所以你得在选择好的命名方式二多费心力,特别是针对公共API提供出来的时候.

我们的命名规范绝大部分和ECMAScript和Flash Player 9 是一致的.

缩写词

作为通用规则而避免使用.例如calculateOptimalValue()比calcOptVal()的命名方式更优.

表意明确比为了少敲几下代码而采用缩写更为重要. 如果你不使用缩写,开发人员就不用非得记住你是否采用了单词简写,如把”qualified”简写成”qual”或”qlfd”.

?不过,我们已经标准化了一些缩写词:

·????????acc 代表 accessibility, 比如 ButtonAccImpl

·????????auto 代表automatic, 比如autoLayout

·????????eval 代表evaluate, 比如EvalBindingResponder

·????????impl 代表implementation, 比如ButtonAccImpl

·????????info 代表information, 比如GridRowInfo

·????????num 代表number of, 比如numChildren

·????????min 代表minimum, 比如minWidth

·????????max 代表maximum, 比如maxHeight

·????????nav 代表navigation, 比如NavBar

·????????regexp 代表regular expression, 比如RegExpValidator

·????????util 代表utility, 比如StringUtil

上述列表可能没有包含目前使用的所有缩写词.如果你用到了上面没有列举出来的缩写词,请搜索源代码看是否已经有相应的缩写词使用了.如果没发现,再考虑一下如果缩写是否合适.

有时我们(故意)采用的缩写词不一致.例如,我们在很多时候都会拼写”horizontal”和”vertical”，像horizontalScrollPolicy 和 verticalScrollPolicy。但是我们在常规容器类名HBox和VBox中却将它们缩写成了H、V，

缩略语

在Flex中有各种缩略语，像AIR, CSS, HLOC, IME,MX, MXML, RPC, RSL, SWF, UI, UID, URL, WSDL, 和XML之类。

一条缩略语要么全部大写要么全部小写（e.g. SWF 或swf，但不会是Swf）。使用全部小写的缩略语形式是当使用本身作为标识符或者作为某个标识符的开头，以及标识符需用小写字母开头时。可以参照一下关于标识符到底以大写还是小写开头的规则一条缩略语要么全部大写要么全部小写（e.g. SWF 或swf，但不会是Swf）。使用全部小写的缩略语形式是使用本身作为标识符或者作为某个标识符的开头，标识符必须以小写字母开头。可以参照一下关于标识符到底以大写还是小写开头的规则.

和缩略语有关的标识符有CSSStyleDeclaration, IUID, uid, IIME和imeMode.

单词定限

当标识符包含多个单词时，我们采用两种方式表明单词界限：单词首字母大写 (比如 LayoutManager 、measuredWidth) 和下划线连接 (比如object_proxy). 具体采用哪种方式请参照一下规则：.

有时候由于不清楚一个单词组合是不是已经成为一个独立的新词了，所以这种情况下会出现不一致的情况：deopdown， popUp，popUp。

即使出现两个缩略语相邻时也要遵循首字母大小写的规则。loadCSSURL()就是一个很符合这种情形的例子（实际上很少使用）。但是尽量避免使用那样的名字。

类型指定名

如果你想要在命名中纳入类型标示，将类型作为最后一个“词”。If you want toincorporate the type into the name, make it the last “word”. 不要使用ActionScript 1的类型连接后缀如_mc表明类型。例如，命名一个border shape，可以是border，borderSkin或borderShape，但不是border_mc.

常常, 对象最简单的名字就是它本身的类型，当然要采取和类型名不同的大小写方式。

var button:Button = new Button();

包名

以小写字母开头然后接下来的单词采用首字母大写：controls，listClasses。

包名总是名词或动名词（动词-ing的名词形式），而非动词，连词或副词。

实现了许多相似东西的包的包名要采用该类事物的复数形式：： charts, collections, containers, controls, effects, events, formatters, managers, preloaders, resources, skins, states, styles, utils, validators.

对于实现了某种概念的包一般用动名词的形式: binding, logging, messaging, printing. 否则, 它们通常只是 "概念名词 ": accessibility, core, graphics, rpc.

一个包含支持FooBar组件的类应当命名为fooBarClasses.

文件名

对于重要的APIs,文件名必须要和公共API内部的名字一致。但是包含文件必须要遵从这个规则：

对于含一个大写字母的元数据[Style(...)] 包含文件的文件名，后续单词采用首字母大写且将最后单词写为”sytles”: BorderStyles.as, ModalTransparencyStyles.as.

以全部小写字母并且下划线进行单词连接的形式来命名个人资产文件: icon_align_left.png.

命名空间名

已全部小写字母并且消化腺进行单词连接的形式命名: mx_internal, object_proxy.

接口名

以I开头并且后续单词使用首字母大写的形式: IList, IFocusManager, IUID.

类名

大写字母开头后续单词首字母大写: Button, FocusManager, UIComponent.

Event子类命名 FooBarEvent.

Error子类命名FooBarError.

Name the EffectInstance subclass associated with effect FooBar FooBarInstance.

Formatter子类命名FooBarFormatter.

Validator子类命名FooBarValidator.

外观类命名 FooBarBackground, FooBarBorder, FooBarSkin, FooBarIcon, FooBarIndicator, FooBarSeparator, FooBarCursor等.

工具类命名 FooBarUtil (不是 FooBarUtils;包名复数但类名要用单数).

常用基类命名方式 FooBarBase: ComboBase, DateBase, DataGridBase, ListBase.

事件名

小写字母开头并且后续单词首字母大写: "move", "creationComplete".

样式名

小写字母开头并且后续单词首字母大写: color, fontSize.

字符串属性枚举值

小写字母开头并且后续单词首字母大写: "auto", "filesOnly",

常量名

全部大写且单词采用下划线连接： OFF, DEFAULT_WIDTH.

常量值如果是string类型的，那么它的value要和常量名保持一致:

public static const FOO_BAR:String ="fooBar";

属性(变量和getter/setter) 名

小写字母开头并且后续单词首字母大写: i, width, numChildren.

使用i作为for循环的外层循环索引值，n作为其上限值. 使用j作为for循环的内层循环索引值，m作为其上限值.

for (var i:int = 0; i < n; i++){

??? for(var j:int = 0; j < m; j++) {

???????...

??? }

}

使用 p (表示 “property”) 作为for-in 循环变量:

for (var p:String in o) {

??? ...

}

如果一个类重写了一个getter/setter，但还想继续公开基类的getter/setter,它就得单独用一个属性，属性吗为基类中属性名前加一个前缀$. 这个getter/setter要以final标记且不做任何额外的coding除了调用super getter/setter.

mx_internal final function get$numChildren():int{

???return super.numChildren;

}

存储变量名

替getter/setter foo命名一个存储变量名_foo.

方法名

小写字母开头并且后续单词首字母大写: measure(), updateDisplayList().

方法名应当总是动词

不带参数的方法不应当采取getFooBar() 或 setFooBar()命名形式,而应设计成getter/setter。不过, 如果getFooBar()是一个需要大量计算的缓慢方法, 应当将其命名为findFooBar(), calculateFooBar(), determineFooBar()等.而不是一个getter.

如果一个类重写了一个方法，但还想继续公开基类的方法,它就得单独实现一个方法，方法名为基类中方法名前加一个前缀$. 这个method要以final标记且不做任何额外的coding除了调用supermethod.

mx_internal final function$addChild(child:DisplayObject):DisplayObject{

???return super.addChild(child);

}

事件处理方法名

事件处理程序名应当在事件类型后面连接一个 “Handler”: mouseDownHandler().

如果处理程序是服务于派发给子控件的事件 (i.e., not this), 在处理程序名前面加一个子控件名前缀然后以下划线后处理程序名组合: textInput_focusInHandler().

参数名

对任何setter的参数使用value 作为参数名:

这样做:

public function set label(value:String):void

而不是:

public function set label(lab:String):void

或者这样做:

public function setlabel(labelValue:String):void

或者这样做:

public function set label(val:String):void

使用 event (而非 e, evt, or eventObj)作为每个事件处理程序的参数:

protected functionmouseDownHandler(event:Event):void

资源包名

如果一个资源包名包含特定包的资源，应该以相同的名字命名这个资源包: controls, {formatters}}, validators.

资源键名

小写字母开头且后续单词首字母大写: pm, dayNamesShort.

杂项名

避免“object” 因为它意义模糊.

一个 “item” 是一个data item, 而不是一个DisplayObject.

一个“renderer” 是一个显示data item的 DisplayObject.

一个“type” 一个AS3 类型; 否则使用 "kind".

语言使用

这部分我们将讨论如何使用AS3的语言构造，尤其当同一事物存在多种表述手段时。

编译选项

采用-strict and -show-actionscript-warnings编译选项进行编译. (在flex-config.xml 文件中会有一些缺省值.)

基于属性的APIs

建议使用基于属性的APIs而不是基于方法的APIs因为这些更加适合声明式的MXML编程

类型定义

为每个常量，变量，函数参数以及函数返回值甚至如果简单地使用:*表明“无类型”。

这样做:

var value:*;

而不是这样:

var value;

使用合适的最紧致的类型。例如，循环变量索引应当是int型，不是Number型，当然更不会是Object或*.另一个例子，mouseDownHandler应当声明一个参数 event:MouseEvent, 而不是event:Event.

整型数使用int, 即使它不是负数.使用uint作为 RGB 颜色值, 位掩码和其他非数字值.

使用 *仅在该值没有定义的情况下. 你应当通常使用Object而不是*You should generally use Object rather than *,具有null代表“对象不存在”值.

如果你声明Array类型的变量,你得添加一个/* of ElementType */形式的注释紧接着Array表明该数组元素的类型。未来版本的语言可能会支持这种类型化的数组。

这样做:

var a:Array /* of String */ = [];

而不是这样:

var a:Array = [];

这样做:

function f(a:Array /* of Number */):Array /* of Object */

{

??? ...

}

而不是这样:

function f(a:Array):Array

文本

undefined

避免使用如果可能的话。仅仅是在编译时变量的类型是*，It is only necessary when dealing with values whosecompile-time is type is *, and you should be using * sparingly as well.

int /uint

不要在integar中使用小数点。.

这样做:

而不是这样:

十六进制数使用一个小写字母x和大写字母 A-Z。

这样做:

0xFEDCBA

而不是这样:

0Xfedcba?

RGB颜色值总是采用这种6位十六进制数表示。

这样做:

private const BLACK:uint = 0x000000;

而不是这样:

private const BLACK:uint = 0;?

Number

如果一个Number值可以是小数,则一般要加上一个小数点并补上0，即使实际值是个整数值

这样做:

alphaFrom = 0.0;

alphaTo = 1.0;

而不是这样:

alphaFrom = 0;

alphaTo = 1;

不过, 对于像素坐标即使是小数形式,也最好使用整数值表示它.

这样做:

var xOffset:Number = 3;

而不是这样:

var xOffset:Number = 3.0;

指数表示法表示数字时使用 e, 而不是 E.

这样做:

1.0e12

而不是这样:

1.0E12

使用值NaN 作为非Number类型的缺省值值.

String

使用引号标记(双引号),而不是撇号(单引号)限定字符串,即使那个字符串包含一个引号作为其内部某个字符.

这样做:

"What's up, "Big Boy"?"

而不是这样:

'What\'s up, "Big Boy"?'

使用\u, not \U, 作为Unicode转义字符序列.

Array

使用数组文本而非new Array().

这样做:

[]

而不是这样:

new Array()

这样:

[ 1, 2, 3 ]

而不是:

new Array(1, 2, 3)

使用Array构造函数仅仅是作为预留数组大小时,比如newArray(3), 意为[ undefined, undefined, undefined ], not [ 3 ].

Object

使用Object文本而非new Object().

这样做s:

{}

而不是这样:

new Object()

这样做:

o = { a: 1, b: 2, c: 3 };

而不是这样:

o = new Object();

o.a = 1;????????

o.b = 2;????????

o.c = 3;

或这样:

o = {};

o.a = 1;????????

o.b = 2;????????

o.c = 3;

Function

避免使用函数文本定义匿名函数;使用一个类方法或包函数替代

如果你必须使用函数文本,声明一个返回类型,在函数体内用一个分号终止最后一条语句.

?这样做s:

function(i:int):void { doIt(i - 1); doIt(i + 1); }

而不是这样:

function(i:int) { doIt(i - 1); doIt(i + 1) }

RegExp

使用字面值而不是一个字符串构造的RegExp实例.

这样做:

var pattern:RegExp = /\d+/g;

而不是这样:

var pattern:RegExp = new RegExp("\\d+","g");

XML and XMLList

使用字面值而不是XML构造函数形式.U

这样:

var node:XML = <name first="Jane"last="Doe"/>;

而不是这样:

var node:XML = new XML("<namefirst="Jane" last="Doe"/>");

对于XML属性值使用双引号括起来:

这样做:

var node:XML = <name first="Jane"last="Doe"/>;

而不是这样:

var node:XML = <name first='Jane' last='Doe'/>;

Class

仅当存在导入类型歧义时才采用类名的全路径形式声明一个类..

这样做:

import mx.controls.Button;

...

var b:Button = new Button();

而不是这样:

import mx.controls.Button;

...

var b:Button = new mx.controls.Button();

但下面这种情况下使用全限定名才是合适的.:

import mx.controls.Button;

import my.controls.Button;

...

var b:Button = new mx.controls.Button();

表达式

括号

对于常用操作符如such as +, -, *, /, &&, ||, <,<=, >, >=, ==, and !=不要使用不必要的括号.

这样做:

var e:Number = a * b / (c + d);

而不是这样:

var e:Number = (a * b) / (c + d);

这样做:

var e:Boolean = a && b || c == d;

而不是这样:

var e:Boolean = ((a && b) || (c == d));

各个操作符的优先级很难记住,所以我们可以运用括号就会十分有用了.

强制转换

不要将Boolean值和true和false比较,因为它的值必然是其中之一.

这样做:

if (flag)

而不是这样:

if (flag == true)

这样做:

var flag:Boolean = a && b;

而不是这样:

var flag:Boolean = (a && b) != false;

很显然强制转换Number,String,XML,XMLList,Array,Object或者*为Boolean，转换错误会有多个值我们很难记住。

类型

你能记起一下哪个是强制转换失败时的值吗?

Number

0, NaN

String

null, ""

XML / XMLList

null, </>

Array

null, []

Object

null, {}, 0, NaN, false, </>

undefined, null, {}, 0, NaN, false, </>

这样做:

if (s != null && s != "")

而不是这样:

if (s)

让Object类型的子类（例如UIComponent）转换为Boolean，因为很明显仅仅null值表示转换失败，其他情况则是转换成功（注意：Object及其子类无法存储undefined值）。

这样做:

if (child)

而不是这样:

if (child != null)

这样做:

if (!child)

而不是这样做:

if (child == null)

对于int和uint，很明显只有0值表示false，其他都为true。所以如果你想要使用显式转换，将其与0比较是没有任何问题的，但是阅读不便。

偏向于塑型作为一个操作符，这个主要为了防止强制类型转换错误评估为null，而不是抛出一个异常。

这样做:

IUIComponent(child).document

而不是这样s:

(child as IUIComponent).document

比较

比较表达式最好以易读的方式书写:

这样做:

if (n == 3) // "if n is 3"

而不是这样做:

if (3 == n) // "if 3 is n"

++ /-- 操作符

为了防止前缀和后缀形式相同，使用后缀形式。如果想要提前使用变量值而不是增加/减少的值可以使用前缀形式

这样做:

for (var i:int = 0; i < n; i++)

而不是这样:

for (var i:int = 0; i < n; ++i)

条件运算符

用条件运算符代替if/else形式，特别是想要检验是否有null值时:

这样做:

return item ? item.label : null;

而不是这样:

if (!item)

??? return null;

return item.label;

主要最好不要将多个条件运算符代替复杂的if/else逻辑结构。

这样做:

if (a < b)

??? return -1;

else if (a > b)

??? return 1;

return 0;

而不是这样:

return a < b ? -1 : (a > b ? 1 : 0);

new运算符

使用括号紧随类型引用，即使这个类的构造函数不带任何参数。

这样做:

var b:Button = new Button();

而不是这样:

var b:Button = new Button;

语句

每条语句后面都要接一个分号，虽然在AS 3中并没有这个强制要求.

这样做:

a = 1;

b = 2;

c = 3;

而不是这样:

a = 1

b = 2

c = 3

include语句

使用include而不是#include. 也像其他语句一样后面加个分号结束.

这样做:

include"../core/ComponentVersion.as";

而不是这样做:

#include"../core/ComponentVersion.as"

使用相对路径而不是绝对路径。

Import语句

导入特定类，接口和其他包级的函数而不是*通配符。

这样做:

importmx.controls.Button;

importflash.utils.getTimer;

而不是这样:

importmx.core.*;

use namespace语句

避免使用它们; 使用 ::语法提到syntax instead on each reference to something in anon-open namespace.

这样做:

importmx.core.mx_internal;

//Later, in some method...

mx_internal::doSomething();

而不是这样:

importmx.core.mx_internal;

usenamespace mx_internal;

//Later, in some method...

doSomething();

if 语句

如果if/else的不同分支涉及到单条语句，不需要大括号包含它.

这样做:

if(flag)

??? doThing1();

而不是这样:

if(flag)

{

??? doThing1();

}

这样做:

if(flag)

??? doThing1();

else

??? doThing2():

而不是这样:

if(flag)

{

??? doThing1();

}

else

{

??? doThing2();

}

但是如果有多条语句时可以将大括号包含起来。

这样做:'

if(flag)

{

??? doThing1();

}

else

{

??? doThing2();

??? doThing3();

}

而不是这样:

if(flag)

??? doThing1();

else

{

??? doThing2();

??? doThing3();

}

如果测试多个error检查，可以使用一系列if语句段测试错误并提前返回。正确的执行流放到最后返回true。不要使用嵌套的if语句来判断，这样会导致执行流整个块中都有.

这样做:

if(!condition1)

??? return false;

...

if(!condition2)

??? return false;

...

if(!condition2)

??? return false;

...

returntrue;

而不是这样:

if(condition1)

{

??? ...

??? if (condition2)

??? {

??????? ...

??????? if (condition3)

??????? {

??????????? ...

??????????? return true;

??????? }

??? }

}

returnfalse;

for 语句

即使for语句块只有一条语句也要用大括号括起来。

这样做:

for(var i:int = 0; i < 3; i++)

{

?? doSomething(i);

}

而不是这样:

for(var i:int = 0; i < 3; i++)

??? doSomething(i);

对于上限我们用一个单独的变量来存储，这样不会使得每次判断的时候都要重复计算。

这样做:

varn:int = a.length;

for(var i:int = 0; i < n; i++)

{

??? ...

}

而不是这样:

for(var i:int = 0; i < a.length; i++)

{

??? ...

}

在循环括号里面声明循环变量，除非其他地方要用到这个变量

这样做:

for(var i:int = 0; i < 3; i++)

而不是这样:

vari:int;

for (i= 0; i < 3; i++)

{

?? ...

}

while 语句

即使只有一条语句也要用括号括起来.

这样做:

while(i < n)

{

?? doSomething(i);

}

而不是这样:

while(i < n)

??? doSomething(i);

do 语句

即使一条语句也要括起来t.

这样做:

{

?? doSomething(i);

}

while(i < n);

而不是这样:

??? doSomething(i);

while(i < n);

switch 语句

将每一个case子句作为一个块，包括default子句。将break和return语句置于块中。将default子句也当做case子句；避免出现case穿透问题。

这样做:

switch(n)

{

??? case 0:

??? {

??????? foo();

??????? break;

??? }

??? case 1:

??? {

??????? bar();

??????? return;

??? }

??? case 2:

??? {

??????? baz();

??????? return;

??? }

??? default:

??? {

??????? blech();

??????? break;

??? }

}

而不是这样:

switch(n)

{

??? case 0:

??????? foo();

??????? break;

??? case 1:

??? {

??????? bar();

??? }

??? break;

??? case 2:

??????? baz();

??????? return;

??????? break;

??? default:

??????? blech();

}

return 语句

不需要将返回值用括号括起来.

这样做:

returnn + 1;

而不是这样做:

return(n + 1);

从方法体中部返回也是可以的

声明

不要在同一行声明多个变量或常量。

这样做:

vara:int = 1;

varb:int = 2;

而不是这样:

vara:int = 1, b:int = 2;

override关键字

如果存在重载的情况，请将这个关键字放在第一位，在访问限定符前面。

这样做:

overrideprotected method measure():void

而不是这样:

protectedoverride method measure():void

访问限定符

在需要访问限定的地方放置上访问限定符。不要不写，虽然这样表示默认的访问限定internal。

在构造public 或者protected的API时，仔细想想是否需要这样做。Public和protected的APIs必须进行文档化。在正式被终止之前需要支持好几个发布版本。

Static关键字

如果存在，请将这个关键字放在访问限定符之后。

这样做:

publicstatic const MOVE:String = "move"

而不是这样:

staticpublic const MOVE:String = "move";

final关键字

如果存在，将它放在访问限定符后面。

这样做:

publicfinal class BoxDirection

而不是这样:

finalpublic class BoxDirection

将所有“枚举类”声明为final型的。

也常常将“基本”属性和方法（以$开头）为final类型。

常量

所有的常量应该是static的。不应将一个实例声明为常量，应该所有的哦实例将使用同样的值。

这样做:

publicstatic const ALL:String = "all";

而不是这样:

publicconst ALL:String = "all";

变量

如果变量需要初始化为一个值，而不是使用默认值，在声明变量的时候就初始化而不用等到构造函数里面再初始化。

这样做:

private var counter:int = 1;

而不是这样做:

private var counter:int;

...

public function MyClass()

{

???super();

??? ...

???counter = 1;

}

局部变量

内部变量在使用的时候才进行声明，而不要都放在函数开始时。

这样做:

private function f(i:int, j:int):int

{

??? vara:int = g(i - 1) + g(i + 1);

??? varb:int = g(a - 1) + g(a + 1);

??? varc:int? = g(b - 1) + g(b + 1);

???return (a * b * c) / (a + b + c);

}

而不是这样做:

private function f(i:int, j:int):int

{

??? vara:int;

??? varb:int;

??? varc:int;

??? a =g(i - 1) + g(i + 1);

??? b =g(a - 1) + g(a + 1);

??? c =g(b - 1) + g(b + 1);

???return (a * b * c) / (a + b + c);

}

Declare local variables only one per function.ActionScript 3 doesn't have block-scoped locals.

Do this:

var a:int;

if (flag)

{

??? a =1;

??? ...

}

else

{

??? a =2;

??? ...

}

Not this:

if (flag)

{

??? vara:int = 1;

??? ...

}

else

{

??? vara:int = 2;

??? ...

}

And this:

var i:int;

for (i = 0; i < n; i++)

{

??? ...

}

for (i = 0; i < n; i++)

{

??? ...

}

Not this:

for (var i:int = 0; i < n; i++)

{

??? ...

}

for (var i:int = 0; i < n; i++)

{

??? ...

}

类

如果一个类简单地继承自Object，不用显示写出extends Object子句。

The only “barestatements” in a class should be calls to static class initialization methods,such as loadResources().

构造函数

如果一个类有实例变量，要书写一个构造函数，显示使用super(),即使它没做任何事情。

如果构造函数参数对应于实例变量，参数名可以使用与实例名同样的名字。

这样做:

public function MyClass(foo:int, bar:int)

{

???this.foo = foo;

???this.bar = bar;

}

而不是这样做:

public function MyClass(fooVal:int,barVal:int)

{

??? foo= fooVal;

??? bar= barVal;

}

不要在构造函数中设置类实例变量；在实例声明时就初始化。不过，如果你需要重置从父类实例中继承的变量值，可以在构造函数中做。

接口

TBD

命名空间

TBD

实现属性

TBD

元数据

TBD

包

在包语句中中的公共API（常常是一个类，有时是一个明明空间或函数）

帮助类

空语句。

文件组织

这部分主要阐释Flex框架文件应当如何组织.

//////////////////////////////////////////////////////////////////////////////

//? ADOBE SYSTEMSINCORPORATED

//? All RightsReserved.

//? NOTICE: Adobepermits you to use, modify, and distribute this file

//? in accordancewith the terms of the license agreement accompanying it.

////////////////////////////////////////////////////////////////////////////////

注意每一行最多包含80个字符.

包语句

TBD

导入语句

TBD

使用命名空间语句

TBD

Class元数据

将类中元数据按Events,Styles,Effects,Excluded IPIs和其它元数据顺序分成几个部分.

在每个部分前面加一个小的说明头.注意每个说明头是40个字符宽度在//和其后区块名之间有两个空格.

每个区块将元数据名”…”按字母表顺序排列出来.在其他元数据区块，将元数据标签名按字母表顺序列出。

//--------------------------------------

//? 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")]

Class声明

TBD

Version.as include语句

每个类应当使用相对路径包含core/Version.as.这个文件包含static const VERSION:String声明.

include "../core/Version.as";

实现注释

TBD

类初始化

TBD

类常量

将静态常量声明置于此。

ActionScript 3 不允许常量具有Array or Object类型. 声明那种常量使用static var而不是static const。将它们放在这个部分因为概念上它们也属于常量。

类最小化

将任何Function类型声明为静态变量而不是声明为方法减小类大小。

类资源

TBD

类变量

TBD

类属性

声明静态getters和setters，然后将它们按字母表顺序排列。使用

Declare static getters and setters here.Order them alphabetically by property name. Use a minor separator with theproperty name for each one. Put the getter before the setter.

类方法

放置静态方法声明.

构造函数

TBD

变量

TBD

重载属性

Put overrides of non-static getters and setters here. Order themalphabetically by property name. Use a minor separator with the property namefor each one. Put the getter before the setter.

属性

Put new non-static getters and setters here. Order them alphabetically byproperty name. Use a minor separator with the property name for each one. Putthe getter before the setter.

重载方法

Put overrides of non-static functions here.

方法

Put new non-static functions here.

重载事件处理函数

Put overrides of event handlers here.

事件处理函数函数

Put new event handlers here.

包外帮助类

TBD

格式化

This section covers how a Flex framework class should be formatted.

行宽度

Wrap code to 80-character lines. This has the following advantages:

·????????Developers with smaller screens don't have to scrollhorizontally to read long lines.

·????????A comparison utility can display two versions of a fileside-by-side.

·????????The font size can be increased for projection before agroup without requiring scrolling.

·????????The source code can be printed without clipping orwrapping.

缩进

Use 4-space indentation. Configure your text editor to insert spacesrather than tabs. This allows another program that uses a different indentationsetting, such as Notepad with its 8-character indents, to display the codewithout disfiguring it.

Section separators

The major section separators inside a class look like this:

???//--------------------------------------

??? //

???//? Overridden methods

??? //

???//--------------------------------------

They extend from column 4 through column 80. The text is indented tocolumn 8.

The minor section separators inside a class, such as between properties,look like this:

???//----------------------------------

???//? visible

???//----------------------------------

They extend from column 4 through column 40. The text is indented tocolumn 8.

Put a single blank line above and below the separators.

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

Metadata

TBD

Do this:

Inspectable[a="1",b="2"]

Not this:

Inspectable[a=1b=2]

Arrayindexing

Don't put any spaces before or after theleft bracket or before the right bracket.

Do this:

a[0]

Not this:

a[ 0 ]

Commas

Follow a comma with a single space. Thisapplies to argument lists, array literals, and object literals.

Arrayliterals

Put a single space after the left bracketand a single space before the right bracket, and put a single space after (butnone before) each comma.

Do this:

[ 1,2, 3 ]

Not these:

[1, 2,3]

[1,2,3]

An empty array is a special case.

Do this:

[]

Not this:

[ ]

Format lengthy array initializersrequiring multiple lines with aligned brackets:

staticvar numberNames:Array /* of String */ =

[

??? "zero",

??? "one",

??? "two",

??? "three",

??? "four",

??? "five",

??? "six",

??? "seven",

??? "eight",

??? "nine"

];

Objectliterals

Put a single space after the left braceand a single space before the right brace, and put a single space after thecolon separating the property name and value.

Do this:

{ a:1, b: 2, c: 3 }

Not these:

{a: 1,b: 2, c: 3}

{a:1,b:2, c:3}

{a:1,b:2,c:3}

An empty Object is a special case.

Do this:

{}

Not this:

{ }

Format lengthy object initializersrequiring multiple lines with aligned braces:

privatestatic var TextStyleMap:Object =

{

??? color: true,

??? fontFamily: true,

??? fontSize: true,

??? fontStyle: true,

??? fontWeight: true,

??? leading: true,

??? marginLeft: true,

??? marginRight: true,

??? textAlign: true,

??? textDecoration: true,

??? textIndent: true

};

Function literals

TBD

varf:Function;

f =function():void

{

??? doSomething();

};

Type declarations

Don't put any spacesbefore or after the colon that separates a variable, parameter, or functionfrom its type.

Do this:

var n:Number;

Not these:

var n : Number;

var n: Number;

And this:

function f(n:Number):void

Not these:

function f(n : Number) : void

function f(n: Number): void

Operators and assignments

Put a single spacearound the assignment operator.

Do this:

a = 1;

Not this:

a=1;

Put a single spacearound infix operators.

Do this:

a + b * c

Not this:

a+b*c

Put a single spacearound comparison operators.

Do this:

a == b

Not this:

a==b

Don't put any spacesbetween a prefix operator and its operand.

Do this:

Not this:

! o

Don't put any spacesbetween a postfix operator and its operand.

Do this:

i++

Not this:

i ++

Statements

Start each statement on a new line, so that you can set abreakpoint on any statement.

Do this:

a = 1;

b = 2;

c = 3;

Not this:

a = 1; b = 2; c = 3;

Align the braces of statement blocks.

Do this:

function f():void

{

??? varn:int = numChildren;

??? for(var i:int = 0; i < n; i++)

??? {

???????if ()

???????{

???????????x = horizontalGap * i;

???????????y = verticalGap * i;

???????}

??? }

}

Not this:

function f():void {

??? varn:int = numChildren;

??? for(var i:int = 0; i < n; i++) {

???????if () {

???????????x = horizontalGap * i;

???????????y = verticalGap * i;

???????}

??? }

}

Constant and variable declarations

TBD

Function declarations

TBD

Do this:

f(a, b)

''Not these:''

f(a,b)

f( a, b )

If the parameters have to wrap, indent the subsequentlines after the left parenthesis. Put multiple parameters per line if they fit.Otherwise, put one per line. If even one won't fit, put the first one on thesecond line, indented past the beginning of the function name.

public function foo(parameter1:Number,parameter2:String,

??????????????????? parameter3:Boolean):void

public function foo(parameter1:Number,

???????????? ? parameter2:String,

??????????????????? parameter3:Boolean):void

public function aVeryLongFunctionName(

???parameter1:Number, parameter2:String,

???parameter3:Boolean):void

Functioncalls

TBD

Do this:

f(a, b)

Not these:

f(a,b)

f( a, b )

ifstatements

Follow the if keywords with asingle space before the left parenthesis. Don't put any spaces after the leftparenthesis or before the right parenthesis.

Do this:

if (a < b)

Not these:

if(a < b)

if( a < b )

if ( a < b )

else if ?

multiline ?

forstatements

Follow the for keyword with asingle space before the left parenthesis. Don't put any spaces after the leftparenthesis or before the right parenthesis.

Do this:

for (var i:int = 0; i < n; i++)

Not these:

for(var i:int = 0; i < n; i++)

for( var i:int = 0; i < n; i++ )

for ( var i:int = 0; i < n; i++ )

If the for clause needs towrap, indent the subsequent lines after the left parenthesis.

for (var aLongLoopVariableName:int =aLongInitialExpression;

????aLongLoopVariableName < aLongUpperLimit;

????aLongLoopVariableName++)

switchstatements

Follow the switch keyword with asingle space before the left parenthesis. Don't put any spaces after the leftparenthesis or before the right parenthesis.

Do this:

switch (n)

Not these:

switch(n)

switch( n )

switch ( n )

Follow the switch keyword with asingle space before the left parenthesis. Don't put any spaces after the leftparenthesis or before the right parenthesis.

Do this:

switch (n)

{

???case 1:

??? {

???????a = foo();

???????break;

??? }

???case 2:

???{?? a = bar();

???????break;

??? }

???default:

??? {

???????a = blech();

???? ???break;

??? }

}

Not these:

switch(n)

switch( n )

switch ( n )

class and interface declarations

braces are always balanced

no braces around single lines

single statement per line

ASDoc文档

属性注释

Only document thefirst function of a get/set function pair for a property. The idiom fordefining and documenting a property is:

/**

?*? @private

?*? The backing variable for the property.

?*/

private var _someProp:Foo;

/**

?*? Place all comments for the property with thegetter which is defined first.

?*? Comments should cover both get and setbehavior as appropriate.

?*/

public function get someProp():Foo

{

? ...

}

/**

?*? @private

?*/

public function set someProp(value:Foo):void

{

? ...

}

Also, ASDoc comments are applied to metadata tags as wellas other constructs within a class so take care that your comments apply to theproper target. If you tag a property as Bindable, your property comment mustprecede the get function, not the Bindable metadata tag.

Do this:

[Bindable("somePropChanged")]

/**

?*? Comments for someProp

?*/

public function get someProp():Foo

Not this:

/**

?*Comments for someProp