【阿順】Flex編碼約定與最佳實踐

Flex SDK 編碼標準與最佳實踐：

 

遵循一定編碼規範能夠使原始碼看起來前後一致、組織良好、更加專業。

本部分內容包括：1. 命名；2. 語言使用 3. 檔案組織 4. 格式 5. ASDoc

 

1. 命名

縮寫：能避免就避免，程式碼清晰永遠比減少打字重要；但是也要記住一些標準化了的通用的縮寫，比如acc(accessiblility) , auto(automatic), impl(implementation), info(infomation), num(number), min(minimum), max(maximum), nav(navigation), regexp(regular expression), util(utility)等等。使用縮寫時儘量和Flex保持一致；

 

首字母縮寫詞：要麼全部大寫要麼全部小寫。當首字母縮寫詞當成一個標誌符或者標誌符的開始部分，且這個標誌符必須以小寫字母開始的時候才採用全部小寫的方式。

 

詞語邊界：標誌符多個單詞構成的時候，單詞首字母大寫，或者詞語以下劃線隔開，比如LayoutManager, object_proxy；當多個首字母縮寫詞鄰接的時候遵循首字母縮寫詞規範，但是儘量避免。

 

指定型別的名字：如果你要將某一個型別組合到一個名字中去，那麼把在加在最後，比如命名命名一個border圖形可以使用：border, borderSkin, borderShape；最好的名字就是型別的小寫比如：Button的例項button。

 

包命名：使用小寫字母，之間大寫字母隔開，比如controls, listClasses；包名稱最好是名詞或者動名詞，不要用動詞、介詞、形容詞、副詞之類。當一個包的作用是實現某一功能的時候最好使用動名詞，比如bingding, logging, messaging, printing；支援元件FooBar的最好寫作fooBarClasses；

 

檔名稱：對於重要的API檔案，檔名稱必須和重要的公開API保持一致，但是include檔案不一定要遵循此規則；對於包含檔案比如用作Styles的，大寫字母開始，各個單詞隔開，且在最後加上Styles: BorderStyles.as, ModalTrasparencyStyles.as； 對於資原始檔小寫字母開始，下劃線隔開：icon_align_left.png；

 

名稱空間名稱：小寫字母、下劃線隔開：mx_internal, object_proxy

 

介面名稱：字母“I”開始、大寫字母間隔：IList, IFocusManager, IUID

 

類名稱：大寫字母開始、大寫字母間隔：Button， FocusManager；Event子類（FoobarEvent），Error子類（FooBarError），皮膚類(FooBarBackground, FooBarBorder, FooBarIcon...)，utility類（FooBarUtil，不是FooBarUtils，包是複數，類是單數）；

 

事件名稱：小寫字母開始、大寫字母間隔：move, creationComplete

 

Style名稱：小寫字母開始，大寫字母間隔：color, fontSize；

 

字元屬性列舉值：auto, filesOnly；

 

常量命名：全部大寫字母，下劃線間隔：OFF, DEFAULT_WIDTH，如果常量是一個字串，那麼常量命名和常量值保持一致: ；

 

屬性名命名：小寫字母開始，大寫字母間隔： i, width, numChildren；

使用i作為選還變數，n作為迴圈上界；使用j作為迴圈變數，m作為迴圈上界：

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

{

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

    {

        ...

    }

}

使用p作為loop迴圈的變數：

for (var p:String in o)

{

    ...

}

如果子類的getter/setter覆蓋了基類的getter/setter，但是同時又想繼續公開基類的getter/setter，那麼這個時候應將基類的屬性名前加上“$”作為子類屬性名，並且子類的屬性名應該標誌為final，且除了呼叫基類getter/setter外不應該做其它的事情：

mx_internal final function get $numChildren():int

{

    return super.numChildren;

}

 

儲存變數命名：getter/setter屬性foo所儲存的變數應該是_foo（加上下劃線）；

 

方法命名：小寫字母開始，每個單詞大寫字母間隔，應該使用動詞：measure(), updateDisplayList()；無參方法應該實現為getter/setter，而不應該是getFooBar(), setFooBar()；當然，如果getFooBar()是一個需要大量計算的慢速度方法的話就應該命名為findFooBar(), calculateFooBar(), determineFooBar()等等，而不是getter；如果子類的某方法覆蓋了基類的某方法，但是同時又想繼續公開基類的某方法，那麼這個時候應將基類的方法名前加上“$”作為子類方法名，並且子類的方法名應該標誌為final，且除了呼叫基類方法外不應該做其它的事情：

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

{

    return super.addChild(child);

}

 

事件處理器命名：在後面加上Handler：mouseDownHandler（）；如果事件處理器是用來處理元件的某一個子元件的事件的話，那麼就應該把子元件的名稱加到最前面，並且用下劃線隔開：textinput_focusInHandler() (textinput的focusin事件的handler)；

 

引數命名：setter值使用value：public function set label(value:String):void; 事件引數使用event：protected function mouseDownHandler(event:Event):void；

 

資源包名稱：為某一包服務的資源包名稱應該和包的名稱保持一致；

 

資源鍵名稱：小寫字母，每個單詞大寫字母隔開；

 

雜七雜八：避免使用“object”，因為它不明確；“item”是資料項，不是顯示物件；renderer是顯示資料項的顯示物件；“type”是AS3型別，否則使用“kind”；

 

2. 語言使用

這個部分討論AS3的語言構造，尤其當某一事情有多種表示方法的時候；

 

編譯選項：編譯的時候要使用-strict –show-actionscript-warnings（flex-config.xml預設）；

 

基於屬性的API：應該偏向基於屬性的API而不是基於方法的API，因為這對於宣告示的MXML來說更加有利；

 

型別宣告：儘量為每個變數、引數、返回值等編寫註釋；引數型別儘量準確，比如迴圈變數應該是int，而不是Number，更不是Object；滑鼠事件處理器的引數應該是MouseEvent而不是Event；如果值可以是undefined的話那麼使用“*”，這種情況下可以使用Object代替，null表示undefined；如果宣告變數為Array，則應該使用“/*   */”馬上註明陣列的成員型別：var a:Array /* of String */ = [];

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

{

    ...

}

 

保留字：

undefined儘量避免使用；

int和uint：整數後面不要加小數點，十六進位制用0x開始，後面的字母大寫；

RGB色通常用六個十六進位制數字表示；

索引值－1表示“沒有索引項”；

Number：通常表示可以帶小數，所以即使變數是整數也應該加上一個小數點和一個零，比如alphaFrom = 0.0; alphaTo = 1.0;但是螢幕座標值不要這樣做；

指數計數的時候使用e，比如1.0e12，不要用大寫E；

String：使用雙引號界定字元，即使字元中間包含引號：字元what’up, “Big Boy”?表示為"What's up, \"Big Boy\"?"， 而不是’what\’s up “Big Boy”?’；

Array：使用“[]”， 而不是new Array()，比如[1, 2, 3]而不是new Array(1, 2, 3)；這裡在一個陣列變數的時候容易出問題，比如一個包含一個值3的陣列，如果用new Array(3)，那麼表示的是建立了一個三個元素的陣列[undefined, undefined, undefined]， 而不是[3]；

Object：使用{}， 而不是new Object()；比如{}, {a: 1, b: 2, c: 3}；

Function：避免使用匿名函式，用類方法或者包方法代替；如果一定要用，那麼宣告返回值，並且函式體內最後一個語句用分號結尾：function(i:int):void { doIt(i - 1); doIt(i + 1); }

RegExp：不要使用正規表示式建構函式建立正規表示式，使用var pattern:RegExp = /\d+/g; 而不是var pattern:RegExp = new RegExp("\\d+", "g")；

XML和XMLList：直接使用保留字宣告，不要使用建構函式。使用var node:XML = ;而不是var node:XML = new XML(""); XML屬性值要使用雙引號括起來，不要使用單引號。

Class：只有當需要在區分兩個匯入類的時候才使用類的全名，

正確做法（Yes：）：

import mx.controls.Button;

...

var b:Button = new Button();

錯誤做法（No：）：

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();

 

表示式相關：對於通用的操作符（+, -, *, /, &&, ||, , >=, ==, !=）不要使用不必要的圓括號；其它的優先順序不容易記住的可以藉助圓括號。

 

強制型別轉換：不要將Boolean變數和true或false比較；顯式的將int，uint, Number, String轉換為Boolean值，使用if(n !=0 ) 而不是if (n)， 使用if (s != null && s != “”)而不是if (s)，對於物件引用來說可以隱式轉換為Boolean值，使用 if (child) 而不是if (child != null)，使用if (!child) 而不是if (child != null)；使用強制型別轉換而不是as操作符，僅僅當強制轉換可能失敗並且你希望失敗的時候值為null而不是丟擲異常。使用IUIComponent(child).document而不是(child as UIComponnet).document；

 

比較：以更容易理解的方式書寫比較表示式: if (n == 3) // "if n is 3"(Yes)， if (3 == n) // "if 3 is n"（No）；

 

++ 和 –操作：字首形式和字尾形式效果一樣的時候使用字尾形式，只有當你想在變數在操作之前使用的時候才使用字首形式；

 

三元操作符：可以使用三元操作符代替簡單的if/else 邏輯，尤其是對null進行判斷的時候；

return item ? item.label : null (Yes)

if (! Item)

return null;

return item.label; (No)

但是不要使用巢狀的三元操作符；

 

new：即使構造的類不帶引數也要使用圓括號：var b:Button = new Button(); （yes） var b：Button = new Button；（No）；

 

宣告：每一個宣告語句都使用分號結尾。

 

include：使用include 而不是已廢棄的#include，和前面一樣，每個宣告語句以分號結束；使用相對路徑而不是絕對路徑；

 

import：匯入明確的類，避免使用萬用字元“*”；

 

use namespace ：避免使用，非公開名字空間引用使用“::”：

Yes：

import mx.core.mx_internal;

 

// Later, in some method...

mx_internal::doSomething(); 

No：

import mx.core.mx_internal;

use namespace mx_internal;

 

// Later, in some method...

doSomething();

 

if：當if/else 分支只有一句宣告的時候，不要用{}括起來；

Yes：

if (flag)

doThing1();

――――――――――――――――――――――――――――――――――――

if (flag)

    doThing1();

else

doThing2():

―――――――――――――――――――――――――――――――――――――

No：

if (flag)

{

    doThing1();

}

―――――――――――――――――――――――――――――――――――――

if (flag)

{

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/12639172/viewspace-331072/，如需轉載，請註明出處，否則將追究法律責任。