コーディングガイドライン(の例) [HTML] [SCSS]

**はじめに**
社内で使いたいと思っているフロントエンドのコーディングガイドラインの草案を載せてみました。
「ここはこうあるべきじゃない？」などいろんな人からツッコミもらえたら嬉しいです。

アウトラインはこんな感じです。

> - [基本仕様](http://qiita.com/volkuwabara/items/c64ba8c81b7dd064ec43#%E3%83%95%E3%83%AD%E3%83%B3%E3%83%88%E3%82%A8%E3%83%B3%E3%83%89%E3%82%B3%E3%83%BC%E3%83%87%E3%82%A3%E3%83%B3%E3%82%B0%E3%82%AC%E3%82%A4%E3%83%89%E3%83%A9%E3%82%A4%E3%83%B3)
- [HTML](http://qiita.com/volkuwabara/items/c64ba8c81b7dd064ec43#html)
- [ディレクトリとファイル](http://qiita.com/volkuwabara/items/c64ba8c81b7dd064ec43#%E3%83%87%E3%82%A3%E3%83%AC%E3%82%AF%E3%83%88%E3%83%AA%E3%81%A8%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB)
- [画像](http://qiita.com/volkuwabara/items/c64ba8c81b7dd064ec43#%E7%94%BB%E5%83%8F)
- [CSS/Sass](http://qiita.com/volkuwabara/items/c64ba8c81b7dd064ec43#csssass)


# フロントエンドコーディングガイドライン


## 基本仕様
* [HTML5(Last Call WD)](http://www.w3.org/TR/2014/WD-html5-20140617/)
* CSS3/[CSS2.1](http://www.w3.org/TR/CSS2/)
* Javascript

## HTML
### 基本ルール
* 要素の終了タグは省略しない
* 空要素のスラッシュ付けない
* および終了タグが不要なタグ(ex. `input` `meta` `img` )の末尾スラッシュは付けない 
* コーディングフォーマットは **Google HTML/CSS Style Guide** に従う。

> Google HTML/CSS Style Guide
http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml

### Doctype宣言
```html:html
<!DOCTYPE html>
```

### エンコード/改行コード
UTF-8、LF を使用します


### 大文字/小文字
小文字のみを使用する
ただしalt属性など値が文字列の場合は使用可能

```diff:sample
- <A HREF="/">Home</A>
+ <a href="/">Home</a>
```

### スペース
必要のないスペースは入れない

```diff:sample
- <p >text</p>
+ <p>text</p>
```

### コメント
HTML/PHPコード中のコメントは `<!-- comment -->` 書式で書きます。
重要なラッパーなどの閉じタグに `<!-- /wrapper -->` などと入れることが多いですが、
昨今のエディタでは、開始/終了タグの対応を視覚的なハイライトで得ることができるため、
必要最小限にすることを推奨します。

また `<!--` の後、および `-->`の前には半角スペースを入れることを推奨します。

```html:sample
<!-- .global-footer -->
<footer class="global-footer">
<div class="container">
:
```

`<!--`の直後に`#`を記述しないでください。SSIのコマンドと誤認されてしまうことがあります。

```diff:sample
- <!--#header-->
+ <!-- #header -->
```


### インデント
インデントは使用しません。
共通ソースコードのインクルード化やphpテンプレート化する際に整合性が保てなくなるためです。

### ファイルパスの記述
#### 同一サイト内のリソース
ドキュメントルートからの相対パスで記述する

```diff:sample
- <a href="img/common/hd_title.png">
- <a href="../img/common/hd_title.png">
- <a href="http://mysite.com/img/common/hd_title.png">
+ <a href="/img/common/hd_title.png">
```

#### 外部ドメインのリソース
プロトコルを省略した絶対パスで記述する

```diff:sample
+ <a href="//othersite.com/img/common/hoge.png">
```


## ディレクトリとファイル

### ディレクトリの命名規則

No | ディレクトリ名 | 配置ファイル
:--|:------------|:------------------
1  | css         | cssファイル
2  | js          | Javascriptファイル
3  | img         | png, jpg, gif, svg
4  | data        | xml, jsonファイル

※ 詳しくはディレクトリ構成図を参照


### ファイルの命名規則

* ファイルはすべてアルファベットの小文字と数字、アンダースコア(_)、ハイフン(-)で構成する
* ドット(.)は拡張子以外では原則使用しない
* 名前に複数の単語を含む場合はハイフン(-)で連結する

※ 各コンテンツの具体的なディレクトリ名はURL設計書に定義されている語に従う


## 画像

### ファイルの命名規則

```css:sample
(接頭辞)_(名前)_(番号/ステート/色).拡張子
```

* 語をつなぐためのハイフン(-)は使用しない
* 節同士（接尾辞、接頭辞をつける場合）はアンダースコア(_)で連結する
* ボタンなどのステートを表す場合はアンダースコア(_)+状態名を付属する
* 明示的に順番が必要なものはアンダースコア(_)+番号(ゼロ埋めはしない)をつけることが可能(a,bなど数字以外の序列表現は避ける)
* 色のバリエーションがあるものもアンダースコア(_)で接尾する
* キャメルタイプは使用しない

### 接頭詞
画像の用途/分類を明示する下記接頭詞をつける

接頭詞 | 意味
:-----|:---------
icon  | アイコン
btn   | ボタン
bg    | 背景
img   | 図版・写真


### 接尾詞
画像の状態を明示する下記接尾詞をつける

接尾詞    | 意味      
:--------|:---------
focus    | フォーカス(マウスオーバー)
active   | アクティブ(タップダウン)
disabled | 非活性
open     | 開いている
checked  | チェックされている
selected | 選択されている
progress | 途中
error    | エラー


## CSS/Sass

### SCSSのファイル構成

SMACSSのように、Base, Layout, Module, ~~State~~, Theme のレイヤーに分けて各SCSSを管理、更新する。(Stateレイヤーについては後述)

```
├ frontend_src/
│   └ scss/
│       ├ lib/                //【Lib    層】
│       │  ├ _variables.scss  // SCSS全体で使用する定数など定義
│       │  ├ _mixins.scss     // SCSS全体で使用する各mixinのimporter
│       │  └ mixins/          // SCSS全体で使用する各mixin
│       │
│       ├ shared/             
│       │  ├ base/            //【Base   層】: サニタイズ, 印刷スタイル
│       │  ├ layout/          //【Layout 層】: 基本ゾーニング, 共通テンプレート
│       │  ├ develop/         //【Develop層】: 開発中のみ使うパーシャルを入れる
│       │  ├ module/          //【Module 層】: 書式, ボタンなど汎用パーツ
│       │  ├ base.scss        // Base,Layout,Develop層のimporter
│       │  └ module.scss      // Module層のimporter
│       │
│       └ {category}/         //【Theme  層】: 固有スタイル
│          ├ {page}.scss
│          └ {page}.scss
│
└ public/                     // 公開領域(ドキュメントルート)
    └ css/                    // コンパイルされたCSS
       ├ shared/
       ├ {category}/
       ├ {category}/
            ： 
```


### SCSSのimporterとpartialの定義

* `module.scss` のように他のSCSSをimportして同ファイル名でCSS出力されるものをScssの「importer(母体)」と呼ぶ
* 一方で、母体から`@import`される「_」から始まるファイル名のものをscssの「Partial(パーシャル)」と呼ぶ

母体となるSCSSファイルでは、かならず文頭でライブラリ層のvariableとmixinをimportし、プロジェクト全体で共通の定数やmixinが呼び出せるようにする。

```sass:SCSS母体の文頭のルール
@charset "UTF-8";
@import "../lib/variables";
@import "../lib/mixins";

// ---------------------------------------------------
// your code here

```

この文頭を定型化するため、原則的にSCSS母体になるSCSSファイルは、同じ階層に置く。

```
scss/
  lib/             // 各SCSS母体から lib への相対パスが等しい
  shared/
    base.scss
    module.scss
  category/
    page.scss
```

一方、パーシャルたちはこのような必須import等を必要としない。

```sass:SCSSパーシャルの文頭
// ---------------------------------------------------
// your code here

```

### SCSSの基本文法

基本的な記述ルールについては **Google HTML/CSS Style Guide** に準拠する
http://google-styleguide.googlecode.com/svn/trunk/htmlcssguide.xml#CSS_Style_Rules

```sample
h1,
h2,                           // カンマ区切りで複数セレクタを指定する場合は改行
.title {                      // セレクタと開始ブラケットの間は半角スペースを開ける
  font-weight: bold;          // インデントは2スペースとし、Tab文字は仕様しない
  color: #999;                // プロパティの後のコロンと、値の間は半角スペースをあける
}                             // 閉じブラケットは改行する
                              // 宣言同士は１行アキを入れる
h3 {
  color: #666;                // 省略可能であれば色値は3ケタに
  border: 1px solid dotted;   // 可能であればショートハンドで書く
}

```

```diff:DON'T
- h1,h2,.title{
-   font-weight:bold;}
```

ただしコードの可読性を高め、ルールのメンテナンス性を保つ必要のある場合は例外とするが、積極的に使う必要はない。

```css:sample

  &.home     { background-image: url(/img/common/img_home.png); }
  &.products { background-image: url(/img/common/img_products.png); }
  &.history  { background-image: url(/img/common/img_history.png); }
  &.support  { background-image: url(/img/common/img_support.png); }
  &.about    { background-image: url(/img/common/img_about.png); }
  
```

### SCSSファイルでのコメント

* Sassのコンパイルでは `//` コメントは削除されるが、 `/**/` コメントはCSSに出力されてしまう。したがって、原則は `//` コメントのみを使用する。
* ただし、デバッグのしやすさの観点で、ルールレイヤーの途切れ目などに必要最小限で `/**/` コメントを残すことは可能とする。
 

### SCSSファイルの命名規則

####モジュールファイル
* 名前に複数の単語を含む場合はハイフンで連結する
* 接尾詞、接頭詞をつける場合も基本はハイフンで連結する


### class名の命名規則

#### IDではなくClassで
コンテンツエリア内では使うパーツにはIDは原則使わず、classで定義する(ぺージで１回しか使用しないものもclassとする)

```diff:sample
- #list-article	
+ .list-article
```

#### 連結子は単数ハイフン(-)のみ
キャメルタイプやアンダースコアは使用しない

```diff:sample
- .listArticle	
- .list_Article
+ .list-article
```
BEM記法のようなダブルハイフンやダブルアンダースコアは使用しない
部分的なオーバーライドやスタイリングをするためのOOCSSクラスを用いることは可能

```diff:sample
- .list--Article__compact	
+ .list-article .compact
```

#### 複数英単語でもClassとして１つの節であれば１語にする
下記例の場合、typefaceとして一つのまとまり(節)になるので１語にする

```diff:sample
- type-face-list
+ typeface-list
```

#### 意味が通らなくなる略語は使用しない
略語は個人差が出て表記ゆれになってしまう。文字列の短さよりも意味の明瞭さを重視する

```diff:sample
- .atcl-ttl
- .artcl-ti
+ .article-title
```

#### 事業や製品名、カテゴリに紐づくclass名をつけるときはURL設計の語彙にしたがう
例：組版製品という意味ですでにディレクトリ名でtypesettingという語が使われているため、新しい語を用いるべきではない

```diff:sample
- .composition
+ .typesetting
```

#### 状態や特性によるスタイルをオーバーライドする場合は、下記classを掛け合わせる

SMACSS命名規則にあるような、`is-`等の接頭辞は使用せず、

```sass:ステートクラス名の例
.active   // 選択されている, 消えているものが表示されている状態
.focus    // フォーカスされている状態
.disabled // 非活性になっている状態
.touched  // タップ中
.compact  // 小さい版
.open     // 開いている
  :
```

※英語として副詞(形容詞)であればそのままの語を用い(例：`open`)、他動詞であれば受動態にする(例：`touched`)にする。またhtml要素の属性名が存在するものは、なるべく同じものを用いる(例：`disabled``selected``checked`)

ただしこれらは元のClassと掛けあわせて使用する前提で汎用的な語にしていますので、Class単独でスタイル定義をしないようにしてください。
(したがってこの思想ではSMACSSにあるStateレイヤーを必要としない)

```diff:sample
- .touched {         // そのものに指定すると影響範囲が大きすぎる
-   opacity: .5;
- }
 
+ .article-title {   // かならず掛け合わせで使う
+   &.touched {      
+     opacity: .5;
+   }
+ }
```