コメントを活用する

Flash

ActionScript のクラスには、必ず JavaDoc スタイルのコメントを書くようにしている。プログラムを流し読みしたときに、コメント部分だけに目を通せば内容が大体把握できるし、関数ブロックの区切りも判りやすい。また、ネストされた if 文や再帰関数のように、人間が理解しづらい部分や、危険なコードの部分にはインラインでコメントを残す。特に、バグの温床となるハードコードされた危険な箇所は、それと判るように統一された記述が好ましい。例えば、"!DANGER" を頭に付けるなどすれば、後々 grep で抽出できる。 

function getHoge():Number {
//!DANGER 何故か 100 を返さないと動きません！
return 100;
}

テストコードにも、コメントは役立つ。トップダウンとボトムアップでコードを記述していくと必ず "つなぎ" の関数が必要になってくる。"つなぎ" の関数は、あくまで動作確認用の不完全な関数なので、一定の値しか返さなかったり、アルゴリズムが単純化されていたりする。これらの存在を見逃さないためにも、それがテストコードであることをマークしておかなければならない。

例えば、イントロに流れるムービーがまだ実装されていないけど、そのムービーを再生するメソッド自体は呼び出したい場合。ここでは、"BEGIN_TEST" と "END_TEST" でテストコードを囲っている。メソッドを呼び出すと、すぐにスキップされて次の段階に進む。 

function playIntroMovie():Void {
//BEGIN_TEST
this.skipIntroMovie();
//END_TEST
}

まだ実装されていない箇所には、さらに "やるべきこと" を併記しておくと、あとで実装するときに指標になる。 

function playIntroMovie():Void {
//イントロを再生する
//再生が終わったら止めて
//次の画面に遷移する
//BEGIN_TEST
this.skipIntroMovie();
//END_TEST
}

他にもいろんなコメントの方法論があると思うけど、僕はこんな感じで書いています。