Vue.js スタイルガイド覚え書き

お久しぶりです。chikamaです。

2020年12月まで半年ほど開発でVue.jsを触っていました。
プロジェクトとしてはまだ続いていますが個人的には一段落ついたため、
このタイミングで公式のスタイルガイドをもとに自分なりの理解を含めた覚え書きを残そうと思います。
長くなるので、特に推奨されている部分にのみ触れています。


Vue.js スタイルガイドとは

プロジェクトでVue.jsを使用する際に、公式から推奨されている記述ルールです。
内容はすべて公式にて紹介されています。
本記事はそれを参考に、筆者の個人的な理解を記したものです。
図での解説もあるため、詳しく知りたい場合は公式を参照してください。

Vue.jsスタイルガイド


Vue.js スタイルガイドについて覚え書き

前提

Vue.jsスタイルガイドのルールは4つのカテゴリに分けられている
本記事ではカテゴリのうちA,Bについてのみ触れる

A・・・必須
B・・・強く推奨
C・・・推奨
D・・・利用注意


A 推奨

コンポーネント名は複数単語にする

目的は二つ。
・HTML等の現在または将来における予約語との衝突を防止すること
・Vueから提供されているコンポーネントと自作コンポーネントを分ける

memo というコンポーネント名ではなく、user-memo などの二語以上の単語で名称をつける。
コンポーネント名を二語以上することでコンポーネントの目的も明確になる。


プロパティ(props)はできる限り詳細に定義する

目的はエラーが起きる可能性を、開発中に警告し、検知させて防止すること
コンポーネントの利用目的が明確になることと、渡されるプロパティを制限することで予期せぬエラーを防止することができる

プロパティは以下のように属性が定義できる。
type : 型
required : 必須 or 非必須
default : デフォルトの値
validator : 細かな制限

type > required > default の優先度でこの三つは定義したい。


v-forを利用するときは必ず一意になるkeyを指定すること

目的は予期しない動作を防ぐこと

keyを指定しない場合、listのindexがデフォルト指定されてしまう。
listの要素は削除することで入れ替わりを起こすため、それによって意図と異なる動作を起こすことがある。

例えばv-forによってlistの中身を画面に表示させているとき
listのindexがkeyになっていると、途中の要素を消しても
順番が入れ替わりを起こすため、最後の要素が消えたように見える場合がある。


v-forと同じ要素でv-ifを使用しない

目的は可読性の低下防止

vue.jsの処理優先度は v-for > v-if のため、同じ要素に対してv-forv-ifを設定すると
v-forによる繰り返し処理のなかでv-ifによって処理が分岐する。

予期せぬエラーを防ぐには処理の目的を明確にすることが大切なので、
目的によって上位の要素と下位の要素と分けて設定すること。


コンポーネント内スタイルのスコープ化

<stype scoped>と記述してスコープ化すること

単一のコンポーネント内要素のみにCSSが当たることになるので、他のコンポーネントのことを気にする必要が無くなる。


ミックスインなどで利用するプロパティには$_プレフィックスをつける

目的はミックスインしたときに他のコンポーネントとの衝突を避けること

$_プレフィックスをつけた上で自身(コンポーネント)の名前をつけてプロパティ名が一意になるようにする。


dataプロパティはオブジェクトではなく、オブジェクトを返す関数でなくてはならない(Vue.js 3スタイルガイドでは削除?)

目的はインスタンス間のdataプロパティの独立性を保つこと

dataプロパティはコンポーネントのインスタンス間で共有される情報のため、
オブジェクトとして定義してしまうとすべてのインスタンスが共通の情報を参照することになってしまう。

dataプロパティをオブジェクトとして定義した場合、
ユーザー間で同じ情報を共有することになるため、Aユーザーが行った動作によって
書き換えられた情報がBユーザーの動作によって上書きされるといった事象が発生する。


B 強く推奨

ファイルはコンポーネントごとに分割する

目的は可読性・検索性の向上

webpackなどのファイル結合ビルドシステムを用いる場合は1コンポーネント1ファイルとして定義する。


コンポーネントのファイル名はパスカルケースかケバブケースに統一する

目的は開発効率の向上
エディタのオートコンプリート機能をうまく働かせるため


継承元となる基底コンポーネントの名前はBaseやAppなどの固定の名前から始める

目的は役割の明確化

コンポーネント設計の大元となるものなので、固定化されたわかり易い名前を最初につけることで役割が明確になる。


ページごとに一回しか利用されないコンポーネントの名前はTheから始める

目的は役割の明確化

ページのHeaderとなるコンポーネントなど、明らかに1ページで1回しか利用されない。
コンポーネントには単一の冠詞Theをつけて役割を強調する。


密結合となるコンポーネントの名前は接頭辞に親コンポーネントの名前をつける

目的はコンポーネントごとのグルーピング

メインとなるコンポーネントに密結合する、部品などを役割とするコンポーネントは
上下関係を明確にするためにメインコンポーネントの名前を接頭辞につける。
フォルダを分けて同一名称をつけるといったやり方は可読性・検索性が落ちるので推奨されない。


コンポーネント名は目的の優先度が高い順で単語を置き、説明を最後にする

目的は表示順の統一

言語として自然かどうかではなく、目的としてレベルの高い単語から始める。
同じ目的のコンポーネントの名前が同じ単語から始まることで表示順番がバラバラにならない。


DOMテンプレート内ではコンポーネント名の形式はケバブケースにする

目的は表記ルールの統一


JS(スクリプト)内ではコンポーネント名の形式はパスカルケールにする

目的は表記ルールの統一


コンポーネント名には略語ではなく完全な単語を用いる

目的はコンポーネントの目的を確実に伝えること
略語では利用目的に誤解の余地を生む可能性があるため


プロパティの定義はパスカルケース、テンプレート内で利用する場合はケバブケースにする

目的は表記ルールの統一


要素に複数の属性を定義する場合は1行ごとに1属性ずつ分けて書く

目的は可動性の向上

1行に全部書くのではなく、属性ごとに改行し、行を分けて書く。


テンプレート内には式は書かない、または簡単な式のみ書いていい

目的はテンプレートとスクリプトで目的を明確に分けること

計算を伴うなどの複雑な式はcomputedかmethodsに移動し、テンプレート上では複雑な処理をさせないようにする。
テンプレートには、「何が表示される」という宣言のみが書かれていることが理想。


算出プロパティは単純にする

目的は3つ
・テストをしやすくする
・可読性の向上
・メンテナンス性の向上

処理が複雑になった場合は複数の算出プロパティに分割し、呼び出す形で処理を構築する。
それぞれの算出プロパティ内でやることができる限り単純化すること。
算出プロパティの処理の入力から出力が単純であればテストもしやすくなる。


HTMLの属性は必ず引用符でくくる

目的は可読性の向上

引用符でくくることで記述に適度な空白ができ読みやすくなる。


ディレクティブの短縮記法は使うか使わないかで統一する

目的は表記ルールの統一

短縮記法については公式ドキュメントを参照。



まとめ・所感

すべてを遵守する必要はなく、必要に応じてプロジェクトごとに変えても良いとのこと。
スタイルガイドを読むのと読まないのではVue.jsの書き方がまるで変わりました。
指標がある程度固まっているとコードを書くときに余計なことに悩む必要がなくなるため楽に書けたなという印象です。

今回の記事は公式のスタイルガイドを参考に、自分なりの解釈を備忘録として残すものですので、ぜひ公式のドキュメントを読んでみてください。


参考

Vue.js v2.x スタイルガイド
Vue.js v3.x スタイルガイド

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

Bitnami