会社やクライアント側で特にコーディングガイドラインが決めれてなかったり、フリーランスだけど結構好き勝手にコーディングしている、なんて時に1つの指針にできるようなコーディングのガイドラインを作ってみました。
また、Compass+SCSS記法を使用する場合はBEM（MindBEMding）を使った方が良いとは思うけど、複数人などのチームで初めて導入する時は少し敷居が高い気がするので、命名規則に関してはOOCSS、略語はMCSSの思想に基づくこととします。
前提
- 上記で書いたように本来はBEMるのがベストだけどあくまでBEMらない時に使うガイドラインです。
- 記述に関して結構当たり前としているところはすっ飛ばします。（CSSでプロパティとバリューの間は空ける、とか）
- 思想だけじゃ足りないルールはプロジェクトファイルにREADEME.mdなどにルールを記載しておくと良いと思います。
- 言わずもがな既にルール化されたクライアント案件のコードには既存の仕様を優先することとします。
HTMLの記述方法について
Googleのガイドラインに準拠する
HTMLの場合、コーディングガイドラインは昔からいろんな企業が作成して公開していますが、クセや会社の方針もあるので、特に指定がなければGoogleが公開している「Google HTML/CSS Style Guide」に沿うこととします。ただし、下記に記載しますがチーム内できちんと統一が取れればGoogle HTML/CSS Style Guideよりもチームのルールを優先します。
チームの意向を優先しても良いもの
タグの省略
Googleのスタイルガイドではタグの省略を推奨していますが、IE8対応の問題や管理性も含め、省略するかどうかはチーム内での意向を優先しても良いと思います。
タグを省略した例
<ul>
<li>Moe
<li>Larry
<li>Curly
</ul>
インデント
HTMLのインデントは半角スペース2つが一般的ですが、タブインデント派やインデントなし派も多いし、最終的にツールを使えば整理ができるので、チームの意向に合わせても良いかと。
IDとクラス名の区切り文字
OOCSSを使用する場合やBEM方式を取らない場合はハイフンつなぎにするのが一般的ですが、スネークケース派も多いのでここもケースバイケースで良いかと思います。
ただし、キャメルケースはJSで使用したりもするのであまり現実的ではないし、スネークケースもBEMを使用する案件もあると混在する可能性があるので、チーム内でよく検討した方が良いと思います。
<!-- ハイフンケース -->
<div class="header-box">
<!-- スネークケース -->
<div class="header_box">
<!-- キャメルケース -->
<div class="headerBox">
img要素のwidth/height
img要素にwidthやheightの属性を入れるかどうかは統一さえしておけば問題ないと思います。HTML5のバリデーションもエラーではないですし。ただし、tableのthなどで指定するのはNGです。
<!-- width/heightを指定した例 -->
<img src="sample.png" alt="sample" width="50" height="50">
画像名について
画像はチーム内で共通したルールがあればそれに合わせれば良いと思いますが、一般的には「-」（ハイフン）か、「_」（アンスコ）でつないでいく方法だと思います。
ただ、よくブレやすい点として、「識別名（buttonやbtnなど）」や「ページ名（homeやtopなど）」の順番や名称が混在しやすくなるので、このあたりはきちんと決めておいたほうが良いです。
画像名の規約で参考に読んでおくと良いもの
コーディングの際の画像ファイルの命名ルールについて
新人コーダーに知っておいて欲しい命名規則の考え方
CSSや画像の命名規則について
CSSの記述方法について
最初に念頭に入れておくこと
OOCSSの思想に基づいているので、下記の3つを常に意識してコーディングをする必要があります。
- パフォーマンス
- 再利用性
- メンテナンス性
セレクタ名
セレクタ名に関しては基本は省略しないものとし、省略するならMCSSの思想に基づき略語辞典を使用するものとします。
（略し方が曖昧だとクラス名が煩雑になるので）
<!-- 略語を使わない場合 -->
<div class="header">
<div class="header-body">
<h1 class="header-title">...</h1>
<p class="header-text">...</p>
</div>
</div>
<!-- 略語を使う場合（略語辞典から参照するようにする） -->
<div class="hdr">
<div class="hdr-bd">
<h1 class="hdr-ttl">...</h1>
<p class="hdr-txt">...</p>
</div>
</div>
idは基本使用しない
headerなどにidを使うのは一般的だし許容範囲でしょ？という考えもあるが、cssのセレクタでidを使用しだすと許容範囲やルールが曖昧になったりするので、基本使わないようにする。
<!-- OK -->
<div class="header">
<h1>...</h1>
</div>
<!-- NG -->
<div id="header">
<h1>...</h1>
</div>
パフォーマンス
CSSのパフォーマンスに留意して記述する。Sassを使う場合はコンパイル後のcssが下記のようになるような記述をする
要素名をつけない
/* OK */
.header {...}
/* NG */
div.header {...}
CSSのネストは孫までにする
子孫セレクタはパフォーマンスに影響が出るが、孫までは許容はする。ただしできるだけ子までにするように心がける
/* OK */
.search-box-input {...}
/* NG */
div.header dl dd .search-box input {...}
できるだけ要素名での指定はしない
CSSは右から左に読み込まれるため、要素名で終わるとそのページの要素を全て探しだす形になります。
見出しタグは入れ替わるケースがあるので、クラス名を付与して指定するようにします。
ただし、<li>タグなど毎度クラスをつけるほどのものではなかったり、<span>タグや<i>タグなどユニークなエレメントの中に存在するものは許容します。
特定の場所に依存するような記述はできるだけ避けるようにします。
/* OK */
.header-title {...}
.item-button span {...}
/* NG */
.header-box h1 {...}
.item dl dd a span {...}
再利用性
Boostrapのクラスのように再利用できるような形でCSSを記述します。
再利用性が高いクラスはWordpressのエディタでも使用されていたりしますよね。
.alignleft {
display: block;
float: left;
}
.button-primary {
display: block;
width: 100%;
padding: 1em .3em;
}
メンテナンス性
OOCSSではコンテナとコンテンツを分離して記述するのと、ストラクチャとスキンを分離して記述する必要があります。
コンテナとコンテンツを分離して記述する例
OK
<div class="column">
<div class="item">...</div>
<div class="item">...</div>
</div>
<div class="column sub-column">
<div class="item">...</div>
<div class="item">...</div>
</div>
.column .item {...}
.sub-column .item {...}
NG
<div class="main-column">
<div class="item">...</div>
<div class="item">...</div>
</div>
<div class="sub-column">
<div class="item">...</div>
<div class="item">...</div>
</div>
.main-column .item, .sub-column .item {...}
.sub-column .item {...}
ストラクチャとスキンを分離して記述する例
<!-- html -->
<button class="btn btn-primary">Login</button>
.btn {
display: block;
cursor: pointer;
width: 100%;
padding: .5em 0;
}
.btn.btn-primary{
background: #f00;
color: #fff;
}
Javascriptの記述方法について
基本的には記述ルールはGoogle JavaScript Style Guideに準拠することとします。
また、変数にはキャメルケースを使用します。
jQueryを使用することが多いとは思いますが、下記のようにcssのセレクタときちんと区別するようにチーム内でルール付けを行う必要があります。
CSSセレクタと区別する例
- jsのセレクタにはすべて「js-hoge」などとcssと区別するような命名規則にする。
- jsには積極的にidを使用する。
【参考文献】
どれも必読です。かなり参考になりマス。