Adobe Open Source
Flex SDKコード記述に関する規則とベストプラクティス

かなり前に英文しか無かったドキュメントの翻訳版。
翻訳自体も2008-05-19、すいぶん前の話。
Flex で調べたいことがあったので Adobe のサイトでガサガサしてたらこのページへたどり着いた。

久しぶりに見たのでクリップしておく。

かなり「後日発表予定」が目につく、で後日ってイツ？
原文も同じ項目が TBD になってるので翻訳の問題ではなさそう。

気になったところをメモ。

命名規則はすぐ分からなくなってしまうので、しっかりメモ。

acc: accessibility（アクセシビリティ）。使用例: ButtonAccImpl
auto: automatic（自動）。使用例: autoLayout
eval: evaluate（評価）。使用例: EvalBindingResponder
impl: implementation（実装）。使用例: ButtonAccImpl
info: information（情報）。使用例: GridRowInfo
num: number（数値）。使用例: numChildren
min: minimum（最小）。使用例: minWidth
max: maximum（最大）。使用例: maxHeight
nav: navigation（ナビゲーション）。使用例: NavBar
regexp: regular expression（正規表現）。使用例: RegExpValidator
util: utility（ユーティリティ）。使用例: StringUtil

名前の一部として型を含めたい場合は、型を示す単語を名前の末尾に結合します。 ActionScript 1の古い規則であったように、略語の接尾辞（_mc}}など）を連結して型を示す方法は使用しないでください。 たとえば、ボーダーのシェイプであれば{{border_mc}}ではなく、{{border、{{borderSkin}}または{{borderShape}}と命名します。

オブジェクトに最も適した名前は、その型の名前を大文字・小文字の記述だけ変えて表したものであることが大半です。

var button:Button = new Button();

小文字で綴りを開始し、以後の連語はキャメルケース方式で記述します。例: controls、listClasses。

名前の綴りを小文字で開始し、各単語間にアンダースコアを挿入します。例: mx_internal、{{object_proxy}}など。

名前の綴りを「I」で開始し、以後の連語をキャメルケース方式で記述します。例: IList、IFocusManager、{{IUID}}など。

大文字で綴りを開始し、以後の連語をキャメルケース方式で記述します。例: Button、FocusManager、UIComponent。

{{Event}}のサブクラスを{{FooBarEvent}}と名付けます。

{{Error}}のサブクラスを{{FooBarError}}と名付けます。

エフェクトの{{FooBar}}に関連付けられた{{EffectInstance}}サブクラスを{{FooBarInstance}}と名付けます。

{{Formatter}}のサブクラスを{{FooBarFormatter}}と名付けます。

{{Validator}}のサブクラスを{{FooBarValidator}}と名付けます。

スキニングクラスには、FooBarBackground、FooBarBorder、FooBarSkin、FooBarIcon、FooBarIndicator、FooBarSeparator、{{FooBarCursor}}などの名前を付けます。

ユーティリティクラスを{{FooBarUtil}}と名付けます。（パッケージは複数形ですが、クラスが単数形であるため、{{FooBarUtils}}にはなりません。）

ベースとなるクラスには、FooBarBase、ComboBase、DateBase、DataGridBase、{{ListBase}}などを用いるのが一般的です。

小文字で綴りを開始し、以後の連語をキャメルケース方式で記述します。例: i、width、numChildren。

ループのインデックスには{{i}}、上限値には{{n}}をそれぞれ使用します。 内部ループのインデックスには{{j}}、上限値には{{m}}をそれぞれ使用します。

for (var i:int = 0; i < n; i++)
   {
    for (var j:int = 0; j < m; j++)
    {
        ...
    }
}

for-in}}ループの変数には、{{p（プロパティの頭文字）を使用します。

for (var p:String in o)
{
    ...
}

クラスがgetter/setterをオーバーライドし、ベースのgetter/setterを公開し続けたい場合は、ベース名に接頭辞「$」が付いた同名のプロパティを実装することで、これが可能になります。 この場合、getter/setterには{{final}}の印を付け、super getter/setterの呼び出し以外の機能を含めないようにします。

mx_internal final function get $numChildren():int
{
    return super.numChildren;
}

getter/setterの{{foo}}のストレージ変数には、{{_foo}}という名前を付けます。

小文字で綴りを開始し、以後の連語をキャメルケース方式で記述します。例: measure()、updateDisplayList()。

メソッド名には必ず動詞を使用するようにします。

一般的に、パラメータのないメソッドには{{getFooBar()}}や{{setFooBar()}}といった名前を付けるのではなく、getter/setterとして実装するようにします。 ただし、getFooBar()}}が大量の演算処理を必要とする「重い」メソッドである場合は、この特徴が明らかになるよう、getterである代わりに、{{findFooBar()、calculateFooBar()、{{determineFooBar()}}といった名前を付けるようにします。

クラスがメソッドをオーバーライドし、ベースメソッドを公開し続けたいような場合は、ベース名の頭に「$」が付いた同名のメソッドを実装することで、これが可能になります。 この場合、当該メソッドには{{final}}の印を付け、superメソッドの呼び出し以外の機能を含めないようにします。

mx_internal final function $addChild(child:DisplayObject):DisplayObject
{
    return super.addChild(child);
}

イベントハンドラには、イベントの種類を示す語句に「Handler」を結合した名前を付けます。

mouseDownHandler()。

仮にハンドラが、サブコンポーネント（this}}以外のものなど）によってディスパッチされるイベント用のものである場合は、ハンドラ名の前にサブコンポーネント名を付け、これらをアンダースコアで結合します。

textInput_focusInHandler()。

各setterの引数には、{{value}}を使用します。

正しい記述例:

public function set label(value:String):void

誤った記述例:

public function set label(lab:String):void
public function set label(labelValue:String):void
public function set label(val:String):void

各イベントハンドラの引数には、（e、{{evt}}および{{eventObj}}ではなく）{{event}}を使用します。

正しい記述例:

protected function mouseDownHandler(event:Event):void

■型宣言に気になる箇所が・・・

{{Array}}データ型を宣言する場合は、{{/* of ElementType */}}の体裁のコメントを{{Array}}直後に記述し、配列要素の型を示すようにします。 将来バージョンの言語では、型付けされた配列が含まれる見込みです。

正しい記述例:

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

誤った記述例:

var a:Object = {}

正しい記述例:

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

誤った記述例:

function f(a:Array):Array

int、uint、{{Number}}および{{String}}は明示的に{{Boolean}}に強制します。

正しい記述例:

if (n != 0)

誤った記述例:

if (n)

正しい記述例:

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

誤った記述例:

if (s)

使用が廃止されている{{#include}}ではなく{{include}}を使用します。 includeステートメントは他のステートメント同様にセミコロンで終了します。

正しい記述例:

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

誤った記述例:

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

絶対パスではなく、相対パスを使用します。

*ワイルドカードを使用する代わりに、特定されたクラス、インタフェースおよびパッケージレベル関数をインポートするようにします。

正しい記述例:

import mx.controls.Button;
import flash.utils.getTimer;

誤った記述例:

import mx.core.*;

if/elseステートメントの分岐後条件に単一のステートメントのみが含まれる場合は、これらをブロックにすることを避けます。

正しい記述例:

if (flag)
    doThing1();

誤った記述例:

if (flag)
{
    doThing1();
}

正しい記述例:

if (flag)
    doThing1();
else
    doThing2():

誤った記述例:

if (flag)
{
    doThing1();
}
else
{
    doThing2();
}

ただし、分岐後の条件部に複数のステートメントが含まれる場合は、すべてをブロックで記述します。

単純な{{if}}/{{else}}文の代わりに三項演算子を使用するようにします。この規則は、特に{{null}}をチェックする際に当てはまります。

正しい記述例:

return item ? item.label : null;

誤った記述例:

if (!item)
    return null;
return item.label;

各{{case}}句の内容、および{{default}}句の内容はブロックで記述します。 {{break}}ステートメントおよび{{return}}ステートメントは、ブロックの後ではなくブロック内に記述します。 returnがある場合は、{{return}}を{{break}}の後に配置しないようにします。 default句はcase句同様に扱うようにし、{{break}}や{{return}}を記述して{{switch}}の最後まで処理が達するのを防ぐようにします。

正しい記述例:

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

このキーワードを使用する場合は、アクセス指定子の後に記述します。

正しい記述例:

public static const MOVE:String = "move";

誤った記述例:

static public const MOVE:String = "move";

定数はすべてstaticにするようにします。 instance定数では、すべてのインスタンスで同じ値が用いられます。したがって、instance定数を使用する理由はありません。

if/else のブロック記述は Flash だとビルトインエディタが勝手にいけてないフォーマットをしてしまう。
Flash CS4 だとどう？？

単純 if/else は三項演算子に変えなさいだって。
でも三項演算子を入れ子にしちゃダメだよ、ってさ。分かりにくくなるからね。

将来バージョンの言語の「型付けされた配列」が含まれる見込み、ってイツになるのでしょう。
パフォーマンスが上がるなら大歓迎！

switch/case も case :{} とカッコでくくりなさいと書いてあった。
サンプルコードはそうなってないから注意しておこう。

update 2010-07-09
「型付けされた配列」は Flash Player 10 から使える Vector のことでしょうね。