Meteor Guide 1.4のCode Styleの意訳

Meteor Guide 1.4のCode Styleを勉強がてら、勝手に翻訳(意訳)してみました。
誤訳があれば、教えて頂けると幸いです

Code Style

コードの推奨スタイルガイドライン

この記事を読むと、以下のことがわかります:

  1. 統一されたコードスタイルを持つことがなぜ良いのか
  2. どのJavaScriptコードのスタイルガイドを我々が推奨しているのか
  3. 自動でコードスタイルをチェックするためのESLintをどうセットアップするのか
  4. MethodsやPublicationsなどの特定Meteorパターンでの推奨スタイルについて

Benefits of consistent style

長年に渡って、開発者はシングルクォーテーションとダブルクォーテーションのどちらを使用するべきかや、どこに括弧を用いるべきか、更にはスペースの数はいくつにするべきかなどのありとあらゆるコードスタイルについて議論してきました。これらの議論はコードの品質とは全く無関係なものですが、目に映る問題であるため、よく議論されます。

文字列に対してシングルクォーテーションを用いようが、ダブルクォーテーションを用いようが、あなたのコードにとってそこまで重要ではありませんが、一度コードスタイルを決めてしまえば、組織を超えてもコードスタイルが統一されるなど多くの利点が得られます。これらの利点は、MeteorやJavaScriptの開発者コミュニティにも同じように提供されます。

Easy to read code

英語の文章を1語ずつ読まないのと同じように、あなたはコードを1単語ずつは読まないでしょう。
たいていの場合、コードのおおざっぱな形やエディター上でハイライトされた箇所を見て、それがどういった処理をするのか想像すると思います。もしコードスタイルが細かく統一されていれば、同じように見えるコードは実際にも同じ処理を行うことが保証されます。隠れた句読点やあなたが予想だにしないような処理などはなくなるため、あなたは記号ではなくロジックの理解に集中できるようになります。JavaScriptにおいて、インデントはそこまで意味はありませんが、インデントはコードスタイルの統一には役立ち、あなたはコードを理解するために全ての括弧を読む必要がなくなります。

Automatic error checking

統一したコードスタイルを持つことは、標準のエラーチェックツールを選ぶことを簡単にします。例えば、varの代わりにletconstを使用することをあなたが選んだ場合、全ての変数が想定したスコープ内に存在することをチェックするツールを使うことができます。また、それによって、変数が予期しない動きをすることを防ぐこともできます。更には、全ての変数が使用される前に宣言することを強制すれば、簡単に誤植を発見することができます!

Deeper understanding

あるプログラム言語の全てを一度に学ぶことは大変です。例えば、JavaScriptを初めて学ぶプログラマーは、たいていvarと関数のスコープで躓きます。自動Lintチェックツールと一緒に、コミュニティ推奨のコーディングスタイルを使用していれば、気づかないような問題に対して事前にツールが警告してくれます。ツールを使用することによって、全てのJavaScriptの極端なケースを学ぶことなく、JavaScriptのコードを飛躍的に習得する事ができます。

コーディングしていると、推奨コードスタイルが嫌になることがありますが、これは、推奨コードスタイルについて考え、より深くプログラミング言語を学ぶ良い機会となるでしょう。

JavaScript style guide

Meteorにおいて、種々の理由からJavaScriptがWebアプリケーションを作成する上で一番良い言語であると強く信じています。JavaScript言語は絶えず進化しており、ES2015スタンダードはJavaScriptコミュニティを一つにしました。ES2015 JavaScriptを使う上での我々の推奨スタイルを紹介します。

Use the ecmascript package

全てのブラウザの標準JavaScriptであるECMAScriptは、毎年、リリースを重ねています。最新のスタンダードはES2015であり、待望された重要な改善事項をいくつか含んでいます。Meteorのecmascriptパッケージは、全てのブラウザで実行できるように、人気のあるBabelコンパイラーを使用して、ES2015を標準のJavaScriptへコンパイルしています。これは、JavaScriptへの完全下位互換性を意味しています。そのため、もしあなたが望まないのであれば、新しい機能を使用する必要はありません。ソースマップなどのブラウザの機能が正常に動くように、我々は努力をしています。その結果、コンパイル結果を見ることなく、好みの開発ツールであなたのコードをデバッグすることが可能になるっています。

ecmascriptパッケージは、標準で全ての新しいappsとパッケージを含んでおり、全ての.jsファイルを自動的にコンパイルします。詳しくは、list of all ES2015 features supported by the ecmascript packageを参照して下さい。

全ての機能を使用するためには、全ての新しいappsを標準で含んでいるes5-shimパッケージを使用することをお勧めします。これによって、ブラウザのサポート状況を気にすることなく、Array#forEachなどのランタイム機能を使用することができます。

このガイド及びMeteorチュートリアルの全てのコードサンプルは、ES2015を使用しています。ES2015については、次のMeteorブログに詳しい記事があります。

Follow a JavaScript style guide

JavaScriptのスタイルガイドを選び、ツールによって遵守させることをお勧めします。人気がありオススメのスタイルガイドは、ES6についても記載されているAirbnb style guideです。 (また、 Reactについても記載があります。)

Check your code with ESLint

“Code Linting”は一般的なエラーやコードスタイルの問題を自動的にチェックするプロセスです。例えば、変数名を誤植したり、if条件が不十分でコードの一部が実行されなかったりすることをESLintは教えてくれます。

私たちは、Airbnbスタイルガイドに記載されているAirbnb eslint configurationを使用することを推奨します。

多くの異なる開発ステージで使える自動lintのセットアップ方法を以降で記載します。最も速く、簡単に誤植と小さなエラーを見つけるため、一般的にできるだけ多くLinterを実行するべきです。

Installing and running ESLint

ESLintをアプリケーションにセットアップするために、次のnpmパッケージをインストールします。

Meteorはnpmバンドル機能を備えているため、心配することなくmeteor npmと入力して大丈夫です。npmコマンドでグローバルインストールも可能です。

Airbnb設定を使用するために、package.jsoneslintConfigセクションを加えることやESLint-plugin-Meteorを有効にすることも可能です。lint npmコマンドによって、お好みの追加ルールを加えることもできます。

linterを起動するためには、次のように入力します。

詳しくは、ESLintのWebサイトのGetting Startedを御覧下さい。

Integrating with your editor

Lintingは潜在バグを見つける最も早い方法です。Linterの実行は、アプリやユニットテストを実行するよりも、たいてい高速です。そのため、常時Linterを実行することは良いアイデアです。あなたのエディタにLintingを設定すると、不格好なコードを保存する度に警告してくれるため、最初は鬱陶しいく感じます。しかし、やがて最初から綺麗なコードを書く週間が身に付きます。エディタ毎のESLintセットアップ方法について、いくつか紹介します。

Sublime Text
Sublime Textパッケージをインストールすることで、テキストエディタにそのパッケージ機能を組み込むことができます。一般的に、パッケージコントローラを使用し、次のパッケージをインストールすることを推奨します。もし既にセットアップ済みであれば、これらのパッケージを追加するだけです。もし未設定であれば、リンクをクリックし、説明を参照て下さい。

シンタックスハイライトを得るためには、.jsファイルにいき、次のドロップダウンメニューを選択します。Syntax -> Open all with current extension as… -> Babel -> JavaScript (Babel)
React.jsxファイルを使用するのであれば、.jsxファイルでも同じように設定します。もし正常に動いているのであれば、.jsファイル(.jsxファイル)を開いている際、ウィンドウの右下に“JavaScript (Babel)”と表示されます。カラースキームについてはpackage readmeを参照して下さい。

Emmetユーザは、.jsxファイル内で\キーをHTMLタグを拡張させるのに使用でき、Reactの”className”プロパティに正確に拡張させることができます。拡張させる機能をTabキーにキーバインドさせることができますし、もし嫌ならここにいろいろと情報が載っています。

Atom
AtomでESLintを使用するのは簡単です。ただこの3つのパッケージをインストールすればOKです。

Lintingを有効にさせるために、Atomをリスタートします(または、Ctrl+Alt+R / Cmd+Opt+Rを押し、リロードします)。

WebStorm
WebStormはESLintのためのWebページを用意しています。ESLint Nodeパッケージをインストールし、package.jsonを設定したら、ESLintを有効にし、”Apply”をクリックします。.eslintrcファイルの場所を設定できますが、私のマシンでは特に変更する必要はありませんでした。WebStormは、”JSX Harmony”シンタックスハイライトへの切替を自動的に勧めてきます。

プロジェクト毎にLintingを有効にできますが、ESLintをエディタのデフォルトに設定することもできます: Editor > InspectionsからDefault profileを選び、”ESLint”を設定します。

Visual Studio Code
VS CodeでESLintを使用するには、サードパティのESLintエクステンションをインストールする必要があります。そのエクステンションをインストールするには、次のステップに従います。

  1. VS Codeを起動し、Ctrl+Pからクイックオープンメニューを表示させます。
  2. コメンどメニュー上でext install vscode-eslintをコピー&ペーストし、エンターキーを押します。
  3. VS Codeをリスタートします。

Meteor code style

これまでのセクションでは、Meteorアプリに特化せず標準的なJavaScriptコードについて紹介してきました。しかし、コンポーネントの構成や名前などMeteor独特のスタイルへの疑問が残っていると思います。

Collections

Collectionの名前は、PascalCaseで複数形の名前にします。データベース内のCollection名(コレクションのコンストラクタの最初の変数)は、JavaScript内の名前と同じにすべきです。

データベースのフィールドはJavaScript変数名みたいにcamelCaseにします。

Methods and publications

methodとpublicationの名前はcamelCaseで、そのモジュール内では名前空間になります。

なお、このコードサンプルでは、Methodガイド内で推奨しているValidatedMethodパッケージを使用してます。もしパッケージを使用しないのであれば、Meteor.methodsへ渡すプロパティの名前を使用します。

publicationへの名前の慣習を紹介します。

Files, exports, and packages

コード管理するためにES2015のimportexport機能を使用するべきです。使用することにより、異なるコード間での依存関係がより理解しやすくなります。また、ソースコードの依存関係を調べる必要がある際に、どこを見れば良いのかを簡単に知ることができます。

アプリケーションの各ファイルは、一つの理論的なモジュールを表すべきです。無関係なファンクションとシンボルをいろいろとエクスポートするような包括的なユーティリティモジュールは避けるべきです。一般的にクラスやUIコンポーネントやcollectionを1ファイル毎に分けることは良いです。しかし、例外もあります。たとえば、そのファイル外で使用されていない小さなサブコンポーネントをUIコンポーネントが含んでいた場合などです。

1つのファイルが1つのクラスやUIコンポーネントを表す場合、ファイル名はその定義するものと(その大文字の使い方も)同じ名前にするべきです。もしそのファイルがクラスをエクスポートしているのであれば、

このクラスは、ClickCounter.jsファイル内で定義されるべきです。このクラスをインポートする際は、次のようになるでしょう。

なお、インポート文では、ファイル拡張子を含む相対パスを使用します。

Atmosphere packagesの場合、pre-1.3以降のapi.exportシンタックスでは、パッケージ毎に1つ以上のエクスポートをサポートしています。そのため、デフォルトではないエクスポートを見かける場合があります。例えば:

Templates and components

Spacebarsテンプレートは常にグローバルであるため、モジュールとしてインポートもエクスポートもできません。更には、アプリケーション全体で、完全にユニークな名前である必要があります。Blazeテンプレートでは、アンダースコア”_”で分けた名前空間へのフルパスを使用することを推奨していました。JavaScript内で簡単にテンプレート名をタイプできるため、アンダースコアを用いることは良いチョイスです。

もしこのテンプレートが、サーバデータをロードしたりルーターへアクセスするようなスマートなコンポーネントの場合、名前に_pageが付くことになります:

テンプレートやUIコンポーネントに携わっていると、複数の似たファイルを管理することになります。それらは、2つ以上のHTMLやCSSやJavaScriptファイルでしょう。この場合、同じ名前のディレクトリに一緒に置くことを推奨します。

全てのディレクトリやパスはListsモジュールに関連しているテンプレートであることを表しています。そのため、ファイル名にその情報を複製する必要はありません。詳細は、ディレクトリ構成を参照して下さい。

UIをReactでコーディングしているならば、名前をアンダースコアで分けるような書き方は必要ありません。なぜならば、JavaScriptモジュールシステムを使用して、コンポーネントのインポートとエクスポートができるためです。