【翻訳】JavaScriptのスタイルガイドとプラクティス by Addy Osmani

AOLの開発者で、jQueryチームのメンバーでもあるAddy Osmani氏の記事「JavaScript Style Guides And Beautifiers」について翻訳の許可をいただいて記事にしました。意訳の箇所も多いですし、翻訳は素人なので、間違いがあればご指摘ください。

JavaScript Style Guides And Beautifiers

今回のテーマはJavaScriptのスタイルガイドです。なぜスタイルガイドが大事なのか、参考になるスタイルガイド、きれいなコードの製作をサポートするツールについて、そして、実際にスタイルガイドに沿ったコードを解説していきたいと思います。

「スタイルガイド」ってなに？

始める前に「スタイルガイド」の定義をおさらいしておきましょう。

スタイルガイド（スタイルマニュアル）は、コードをデザイン・記述するための標準（ルール）のセットです。スタイルガイドはでコードのスタイルとフォーマットの画一性を提供します。内容としてはインデント（タブか半角スペースか）や変数、関数の命名規則、コードのどの部分に半角スペースを記述するのがよいかなどが定められています。

なぜ一貫したコードスタイルが重要なのか？

多くの人が「よいコードはそれ自身が仕様書だ」といいます。私自身はそれに完全には同意しませんが（仕様書は重要です！）、重要なのは読みやすいコードを心がけることで、コードのメンテナンスもやりやすくなるということです。

一貫したスタイルガイドを適用することで、このコンセプトの実現を容易にすると同時に、コードのクオリティを高めることにもつながります。これによって、他の開発者の手を借りる際に、容易にメンテナンスができ、（コードの解読などに）時間をとられることも減ることでしょう。

読みやすいソースコードは私たちにも理解しやすいものです。目を通すのも楽ですし、バグの発見や修正も容易になります。また最適化もずっと楽になります。また巨大なソースコードの中で、個々のコードがどのように組み込まれているかも、クリアにイメージもできるようになります。これは別にスタイルがきちんとされていないコードが悪い（記述の）コードという意味ではありません。スタイルがほとんど適用されていないにもかかわらず、全体を通してみれば非常に効率的な記述をされているコードをいくつも見たことがあります。

繰り返しますが、スタイルを適用したコードは

・実装を理解するためのリードタイムを減らすことができます。
・コードの再利用ができることを確認するのを簡単にします。
・実装のアップデートをする際にもどのようにスタイルするか、構成をどのようにするかを明確化できる（覚えておいてください。このような一貫性のあるコードは、たとえチームで記述したとしても一人が書いたように見えるものです）。

実際のところ開発者は作業にスタイルガイドを使っているの？

スタイルガイドの利用は多くの人に支持されています。しかし実際のところ全体の１％しかきちんと使っていないとしたら、役になっているとはいえないでしょう。もう少し実体を把握するために、ツイッター上で「JavaScriptを書くときにスタイルガイドを使っているか」開発者にたずねてみました。

結果、多くの参考になる意見をいただきました。以下にそのうちのいくつかを挙げてみます。

・Rodney: jQueryスタイルガイドをよく使っているよ。あのばかげた量の半角スペースを除いてだけどね。
・Sindre: 当然Idiomatic.jsだよ。シングルクオートとタブインデントにしてね。
・D.Cherman: 僕らのグループでは使ってはないね。でも僕自身はideomatic.jsに従うようにプッシュしてるよ。
・Marek: 参加しているプロジェクトが別のものを使っていない限り、いつもクロックフォードスタイルを使っているよ。
・Jack: 自分で作ったJSスタイルガイドに従っているよ。出回っているガイドラインを組み合わせたもので、大体似ている。
・Matt: 使ってる（jQueryとIdiomaticをベースにして）。でもプロジェクトによってはフレキシブルに対応するよ。
・Jamie: チームに参加していたときには既存のやつを使った。１人じゃないときは標準を決めるね。一人で作業する限りどんなスタイルでもいいと思うよ。標準を使うと一人が書いたように読めるからね。まぁ僕個人の意見ではあるけど（訳注：訳が間違ってるかも）
・Arthifiji: 仕事でgoogleのコーディング＆スタイルガイドラインを使おうと計画しているところ。すごく包括的だと思うよ。

お勧めのJavaScriptスタイルガイド

スタイルガイドを使ってみようかな、と思っている開発者の人のために、以下のスタイルガイドをお勧めします。

１．Idiomatic.js
このスタイルガイドは特に強くお勧めされるわけでも包括的なわけでもありません。しかし、これまで私の参加したいくつものプロジェクトで採用してきました。このガイドの開発者にはjQueryコアの開発者であるRick Waldron氏、jsPerfの開発者Mathias Bynensをはじめとして、jsコミュニティーで著名な開発者が参加しています。すべての開発者が100％同意するものではありませんが、＃forkしやすいスタイルガイドという点でとくに優れています＃。あなたの必要に応じて採用できます。

２．jQuery Core Style Guide
おそらくモダンなJS開発者にとって一番ポピュラーなスタイルガイドで、jQueryコアチーム、jQueryUI、QUnitなど多くのプロジェクトで採用されています。こちらにもRick Waldron氏が参加しており、Adam Sontag氏やJohn Resig氏といったjQueryの有名人が参加しています。

３．Google JavaScript Style Guide
有名なGoogleのJavaScript開発者Robby Walker氏(Closure Linter)によるスタイルガイド。特にソフトウェアエンジニアリングの経験を持つ人にとって、読みやすくするためのベストプラクティスが多く含まれています。詳しいコメントはこちらから見てみてください。

４．Dojo Style Guide
dojo toolkitの開発者による、もうひとつの非常に包括的なスタイルガイドです。面白いことにこのスタイルガイドはJava programming conventions guideの構成を基にしています。これを読んで気に入ったのであれば、dojoのinline documentation guideを読んでみるのもよいでしょう。私のお気に入りのJSファイル中へのインラインコメントの記述方法です。

５．Aloha Editor JavaScript Style Guide
このガイドは組み込み型HTML5エディタAloha Editor（the relatively non-trivial contentEditable-based）の開発者によるものです。ガイド中でjQueryスタイルガイドを参照するように推奨されていますが、どのようにAMDモジュールをスタイルするかなど、いくつかの小さな役立つ追加点があります。

６．Crock's Code Conventions For JavaScript
ほかとくらべてサンプルの詳細などで劣りますが、もうひとつの優良なガイドです。見たところIdeomatic.jsによって取って代わられたようです。しかしあなたがIdeomatic.jsやjQueryコアスタイルガイドに同意できないのであれば、代わりとしてこれを使うことをお勧めします。

２人の開発者からNPM style guideをプロジェクトで使用していると聞きましたが、リストには入れませんでした。このガイドラインは邪魔な視覚要素をはぶいて最小限にしてありますが、実際の内容はその他のガイドラインと同等のもので、軽量版ガイドラインと呼ぶのがふさわしいでしょう。おすすめした１～６のガイドラインはより包括的なガイドラインとなります。

注：私は上にあげたガイドラインをすべてレビューしたうえで、簡易であったり明確でないためにあまり役に立たない（私の意見ですが）スタイルガイドを不採用にしました（the GitHub JavaScript style guideなど）。

実際にIdiomatic.jsのスタイルを適用させるチュートリアル

簡単なチュートリアルをやって見ましょう。ここにどのガイドラインも適用されていない関数があります。

function foo(bar,baz,fum){  
    var hello = "Hello";  
    var ret;  
    var num = 1;  
    for(var i = 0; i < bar.length; i++) {  
        var out = bar[i];  
        if (out === ""){  
            ret = fum(out) + baz(out);  
        }  
    }  
    if (!(ret == undefined)) {  
        return ret;  
    } else{  
       return fum('g2g');  
    }  
}

技術的にはなんの問題もなく動作しますが、まだ改善することができます。

一貫して読みやすいコードを適用させることで、どのような効果があるかをよりよく理解するために、このサンプルにIdiomatic.jsの内容をひとつずつ適用させていってみましょう。

変更前と変更後を比較して、スタイルを適用させるとどう変わるか一目で分かるようにして、ステップごとに解説をしていきます。

1. 関数の宣言

適用前

function foo(bar,fum,baz){

適用後

function foo( bar, fum, baz ) {

・すべての引数の前に一貫して半角スペースを追加
・引数を囲む括弧の内側にそれぞれ半角スペースがあることを確認
・引数の閉じ括弧")"とブロックの開始括弧"{"の間に半角スペースを追加

2. 変数の宣言

適用前

var hello = "Hello";
var ret;
var num = 1;

ループ部分にも変数があるのでそれもまとめます

for(var i = 0; i < bar.length; i++) {
    var out = bar[i];

適用後

var ret,
    out,
    hello = "Hello",
    num = 1,
    i = 0,
    l = bar.length;

・読みやすくするためにひとつの関数にひとつのvarで変数を宣言するようにします。Idiomatic.jsによるとゴミ（訳注："var"？）を減らすことができます。
・ループ部分で宣言されている変数"i"を同じvarの中に含めます。また、bar.lengthを毎回計算しないように変数"l"に代入してキャッシュします。
・ひとつの関数でひとつのvarというルールに基づき、変数"out"もこの宣言に含めるようにします。

3. ループ

適用前

for(var i = 0; i < bar.length; i++) {

適用後

for ( ; i < l; i++ ) {
    out = bar[i];

・ループ宣言で一貫した半角スペースを使用するようにします。
・具体的には(i)"for"と"("の間、(ii)すべての式と文の間、(iii)ブロックの開始括弧"{"の前
・すでに変数"i"に"0"を代入してあるので、これを省略してセミコロン";"だけを記述する。いくつかの開発者はこれでゴミを減らせると主張しています。

注：ループカウンターの宣言を関数の先頭にもってくるのはスタイル的な選択です。これに不都合を感じるのであれば、これを採用しなくても問題ありません。私個人は変数をトレースできるように、普段はインラインで記述します。

4. 条件の評価

適用前

if (out == ""){
    ret = fum(out) + baz(out);
}

適用後

if ( !out ) {
    ret = fum( out ) + baz( out );
}

・"out"が空かどうかの判定は、真偽判定を使用できます（例："!out"）。これによってキーストロークの数も減り、可読性も増します。
・これまでしてきたように、関数呼び出しの引数の前後に半角スペースを記述して、読みやすくします。

5. さらに条件の評価

適用前

if (!(ret == undefined)) {
    return ret;
} else{
   return fum('g2g');
}

適用後

return ret || fum('g2g');

・ここでは"=="による評価は使用しません（どちらにしろここでは"==="を使用するべきです）。
・"!(ret == undefined)"は4.と同様に真偽判定を利用して"!(ret)"と記述できます（ですがこれはさらに改善できます）。
・適用前のような冗長な記述方法ではなく、論理演算子の特性を活かすことができます。"ret"が"undefined"もしくは"false"の場合はつぎの条件にうつるため、これを利用して5行あったものを、ずっと少ない文字数にでき、可読性もあがります。

最終結果

function foo( bar, baz, fum ) {
    var ret,
        out,
        hello = "Hello",
        num = 1,
        i = 0,
        l = bar.length;
    for ( ; i < l; i++ ) {
        out = bar[ i ];
        if ( !out ) {
            ret = fum( out ) + baz( out );
        }
    }
    return ret || fum('g2g');
}

注：このサンプルにはまだまだ改善できる箇所があります。まずは、引数である"bar"、"baz"、"gum"の内容のチェックなどがあるでしょう。ですが、今回はスタイルの適用のチュートリアルということで無視しています。

結論・ティップス

・あなたのコードにおいて、一貫したフォーマットとスタイルを維持することには、いくつものアドバンテージがあります。それには既存のスタイルを利用してもいいですし、自身のオリジナルのガイドを作ってもいいでしょう。多くの開発者が、個人的なガイドラインを作ることが便利と感じていますし、ほかのものより優れていると感じています（訳注：最後のフレーズ違うかもしれません）。
・半角スペースの効果的な使い方をしてください。可読性があがります。
・変数や関数、モジュールの名前には短く意味のある名前をつけましょう。これによって、インラインコメントで詳細を説明する手間を省けますし、開発者がすぐにコードを読み込むことができます。
・繰り返しのコードや、もっと短く読みやすく書き直せるコードを書くべきではありません。これは別に、すべてにおいて第三者のオペレーターを使うとか、今回のサンプル通りにしなければいけないわけではありません。読みやすいのであれば、長い記述でも問題ありません。
・YAGNI（You are not going to need it）やKISS（Keep it short and simple）などの原則に可能な限り従いましょう。冗長な記述をさけ、より簡潔で読みやすいコードを書く助けになります。

beijaflor