2016年版 フロントエンド開発フォーマット

フロントエンドフロントエンドの開発効率をあげるテンプレートと

その使い方やルールを説明します

株式会社スタジオ・アルカナ

開発フォーマット

目的「一貫性を持たせる」開発、命名、フォルダ構造にルールを定めることで、共通の語彙を持つことができ、プロジェクトを 1 人の開発者に依存しないようにします

対象• プロジェクトに関わる人全般• HTML / CSS の知識があることを前提とする• 静的なページのみのコーディングを想定とする

使用ツール ( 事前知識 )• CSS Preprocessor: Sass （ scss 記法）• Reset CSS: sanitize.css• HTML Template Engind: Jade• TaskRunner: Gulp• VersionControlSystem: Git

得られる恩恵1. コードの品質の安定

慣例・定石の例をまとめることで品質 ( 拡張性 , メンテナンス性 , 可読性 , バグの回避 ) を担保する

2. コミュニケーションコストの削減ルールに沿った書き方をする事で連絡や質問事項を減らす

3. 経験値の共有HTML/CSS の仕様上起きやすいミスを防ぐ

環境設定 CSS のルール

HTML のルール

HTML/CSS 共通ルールGit のルール

アジェンダ

画像のルール

環境設定 CSS のルール

HTML のルール

HTML/CSS 共通ルールGit のルール

環境設定

画像のルール

準備すべき環境• Node.js(v5.4.1)• Git• Gulp(4.x)• Sass• Jade• EditorCoding

使用方法1. ファイルを作業フォルダに落とす$git clone https://github.com/KodairaKenya/web-starter-kit.git

2. パッケージをインストール$npm install

3. 実行$gulp

ディレクトリ構造少し見えずらいけど、この構造が大切になります！！

環境設定 CSS のルール

HTML のルール

HTML/CSS 共通ルールGit のルール

Git のルール

画像のルール

Git( コミットのルール )バージョン管理ツールの主流とされている Gitコミットメッセージに一定のルールを与えることで、共同開発者が何を行なったかを一目でわかるようにします( 今回は日本語でのコミットを想定します )

原則• 1 行目に全体的説明 ( タイトル ) を 50 字以内で記述• 2 行目は空白行• 3 行目以降に変更内容の詳細 ( 何をなぜ ) を記述

コミットメッセージの原則的なルール

1 行目の記述フォーマット• 【 Fix 】 ：バグ修正• 【 Add 】 ：新規機能（ファイル）追加• 【 Change 】 ：仕様変更• 【 Remove 】：削除（ファイル）

日本語でのコミット例【動詞】ページ名 / 説明の形にする

$ git commit -m " 【 Fix 】 about / フッターリンクを修正 " -m "( 空白 )" -m " リンク先をA から B に修正 "

( 例 ) about ページの footer のリンクを修正

( 例 ) contact ページの住所の欄を追加$ git commit -m " 【 Add 】 contact / 住所の欄を追加 " -m "( 空白 )" -m " データーベースに合わせて住所を入力する欄を追加する "

.gitignore基本的に gulp で処理した後のファイルは git で管理しない下記のファイルはアップしないようにする/.DS_Store/node_modules/build/npm-debug.log

環境設定 CSS のルール

HTML のルール

HTML/CSS 共通ルールGit のルール

HTML のルール

画像のルール

HTML( 基本の書式ルール )HTML の書式のルールを定義しますコードの品質が維持される場合に限り、難読化、最小化、コンパイルするのは自由です

一般的な書式ブロック要素ごとに改行し、子要素にはインデント ( スペース 2 つ ) をつける(a 、 span 、 img などの最小の位置にでは改行は適宜対応 )理由可読性の向上

( 例 )/* NG */<div> <ul> <li><a href="/">Moe</a></li> <li>Larry <li>Curly </ul></div

スペースは 2 つ

プロトコル２つのプロトコル (http:/ https:) をまたがって使わざるを得ない限り、画像や他のメディアファイル、スタイルシート、スクリプトの URL からプロトコル部分を省く理由ファイル容量を少なくできる

( 例 )

/* NG */div { background: url(http://www.google.com/images/example);}/* OK */div { background: url(//www.google.com/images/example);}

<!-- NG --><script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script><!-- OK --><script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

http: が省略されている

スペースインデントはスペース２つ( エディタの設定で tab でスペース 2 つ入力されるように設定しておく )

理由見た目を綺麗に揃えるため

エンコーディングエンコーディングを明記するmeta charset=”utf-8″ のように明記

理由文字エンコーディングを指定しないと、日本語で作成されたウェブページに英語版のブラウザでアクセスした場合などに文字化けが起きることがある

コメント「何のため誰が入れたのか」をコメントとして記述する参考 URL があればそれを貼り付ける( コメントが多くなったら命名やコードを見直すこと検討 )

理由コメントを明確に残すことで、他の開発者も触れるようにする

正しい HTML を使う悩んだら W3C に目を通してみるhttp://momdo.github.io/html5/dom.html#dom

理由W3C の規定に沿うコーディングを目指すSEO の考慮と対立した場合は、 W3C の規定を優先する

構造の分離プレゼンテーション（スタイル）と振る舞い（スクリプト）は、ストラクチャ（マークアップ）から分離する理由メンテナンス性の向上ファイルが分割し依存しないことで安易に修正が行える

( 例 )<!-- NG --><h1 style="font-size: 1em;">HTML sucks</h1>

<!-- OK --><link rel="stylesheet" href="default.css"><h1>My first CSS-only redesign</h1>

外部ファイルからスタイルを当てている

文字参照「 < 」や「 & 」のように HTML で特別な意味を持つものや、特殊スペースのような「見えないもの」以外で文字参照を使うことを避ける理由文字参照は主に「 < 」「 > 」が必要になってくる場面で使用することは許容するが、対応していない機種なども考慮するとそれ以外ではあまり使うべきではない

( 例 )<!-- NG -->The currency symbol for the Euro is “&eur;”.

<!-- OK -->The currency symbol for the Euro is “€”.

なるべく文字参照は NG

マルチメディアの設定alt属性でアクシビリティー向上のために画像が何を意味しているのか記載する

理由画像に対して代替として動作するテキストをユーザーに提供できる

( 例 )<!-- NG --><img src="spreadsheet.png">

<!-- OK --><img src="spreadsheet.png" alt="Spreadsheet screenshot.">

alt属性の入力はユーザーへの気遣い

type属性CSS と JavaScript の type属性は省略

理由HTML5 から type属性は省略可能になったので、ファイル容量の削減

( 例 )<!-- NG --><link rel="stylesheet" href="//www.google.com/css/maia.css" type="text/css">

<!--OK --><link rel="stylesheet" href="//www.google.com/css/maia.css">

type属性は必要ない

a タグリンクはルート相対パスを基本とする(注意：案件によって柔軟に変更する )

理由ファイル容量の削減記述方法の統一化

HTML クォーテーション属性値に使うクォーテーションは、シングル（”）よりもダブル（””）が好ましい

理由JavaScript は HTML の中で使用するのが想定されるため、HTML はダブルクオーテーション ("") で JavaScript はシングルクオーテーション ('') を使用するのを推奨している

( 例 )<!-- NG --><a class='maia-button maia-button-secondary'>Sign in</a>

<!-- OK --><a class="maia-button maia-button-secondary">Sign in</a>

HTML 内ではダブル ("") にする

環境設定 CSS のルール

HTML のルール

HTML/CSS 共通ルールGit のルール

CSS のルール

画像のルール

CSS( 基本の書式ルール )

CSS 設計 ( 前提知識 )CSS の教科書http://goo.gl/MspHyM

CSS 設計手法CSS 設計は FLOCSS を使用するhttps://github.com/hiloki/flocss

CSS ファイル1 つのコンポーネントごとにファイルを分割するファイル名はコンポーネントに使用しているクラス名を用いる理由保守性が向上するため

ID と Class の命名ID とクラス名にはちゃんと意味の分かる名前を使う見た目を反映したものやそれが何を表しているか不可解な名前ではなく、要素の目的や役割を反映した名前を付ける理由制作した当事者以外が把握できるようにするため修正に耐えやすいため

( 例 )

/* NG クラス名だけだと把握できない */.table01 {}

/* NG: 見た目を表してる */.btn-green {}

/* OK */.btn-primary {}

/* OK: 役割を表してる */.gallery {}.login {}.video {}

何を示しているのかがわかる命名を意識する

ID とクラスの命名スタイル意味の分かる範囲でできるだけ短い ID とクラス名を使う注意：短くしすぎて意味がわからなくなるようなのは NG

理由ファイルサイズ節約のため

( 例 )/* NG */#navigation {}.atr {}

/* OK */#nav {}.author {}

※.atrだと省略しすぎ

IDID は原則使用せずクラスで対応する( ページ内リンクで使用する場合は例外とする )

理由再利用性が低下するため( 詳細度が高くなり管理しづらいため )

タイプセレクタの記述ID とクラス名にタイプセレクタは記述しない

理由限定された要素以外に適用できなくなり、再利用性が低下するため

( 例 )/* NG */ul.example {}div.error {}

/* OK */.example {}.error {}

要素に依存しないようにする

ショートハンドプロパティショートハンドを適宜使用する

理由ファイル容量の節約のため

( 例 )/* NG */padding-bottom: 2em;padding-left: 1em;padding-right: 1em;padding-top: 0;

/* OK */padding: 0 1em 2em;

ショートハンドプロパティで記述量を減らす

「 0 」と単位値が「 0 」なら単位を省略する

理由ファイル容量の節約のため

( 例 )/* NG */margin: 0px;padding: 0px;

/* OK */margin: 0;padding: 0;

小数点の頭の「 0 」小数点の頭の「 0 」は省略する

理由ファイル容量の節約のため

( 例 )/* NG */font-size: 0.8em;

/* OK */font-size: .8em;

.数字にして記述量を減らす

URI 値の引用符url() での指定において、("") ダブルコーテーション、 ('') シングルコーテーションの URI 値の引用符を省略する理由ファイル容量の節約のため

( 例 )/* NG */background-image: url("//www.google.com/css/.css");

/* OK */background-image: url(//www.google.com/css/.css);

("") を省略する

カラーコードカラーコードで 3文字で表記できるものは 3文字にする

理由ファイル容量の節約のため

( 例 )/* NG */color: #ffffff;

/* OK */color: #fff;

CSS 書式ルール

理由可読性向上のため

ブロック単位のインデント階層がわかるようにブロック単位でコードをインデントする

( 例 )@media screen { html { background: #fff; color: #444; }}

インデントは半角スペース 2つ

プロパティの終端

理由可読性向上のため

すべてのプロパティの終端はセミコロンを書くこと

( 例 )/* NG */.test { display: block; height: 100px}

/* OK */.test { display: block; height: 100px;}

プロパティの終端には必ずセミコロン (;) を書くようにする

プロパティ名の終端

理由可読性向上のため

すべてのプロパティ名の終端にはコロンの後にスペースを入れること

( 例 )/* NG */h3 { font-weight:bold;}

/* OK */h3 { font-weight: bold;}

半角スペースを一つ空ける

セレクタの終端

理由可読性向上のため

"{" の位置は、セレクタと同じ行に記述するセレクタとの間にはスペースをいれること

( 例 )/* NG */.sample{　 color: #399;}

/* NG */.sample{　 color: #399;}

/* OK */.sample {　 color: #399;}

記述方法を統一する

セレクタとプロパティの分離

理由可読性向上のため

別々のセレクタとプロパティは改行して書くこと

( 例 )/* NG */h1, h2, h3 { font-weight: normal; line-height: 1.2;}

/* OK */h1,h2,h3 { font-weight: normal; line-height: 1.2;}

CSS ルールの分離

理由可読性向上のため

別々の CSS ルールは改行して一行間を空けて書く

( 例 )/* NG */html { background: #fff;}body { margin: auto;}

/* OK */html { background: #fff;}

body { margin: auto;}

改行を 1 つ空けるようにする

コメント

理由当事者以外が把握しやすくするため

必要に応じてコードを説明するコードに TODO を入れ、何のためのものか誰が入れたのかをコメントとして記述する

BEM のセパレーター

理由こちらの方が普及してるため本来の BEM よりもセパレータが識別しやすいため

MindBEMding を採用するblock__element--modifier

BEM の粒度

理由冗長なクラス名をさけるため参考： http://qiita.com/hiloki@github/items/4fa99b8755a22878449e

block__element__element は使用しないblock との関係性を明示していれば問題ない

( 例 )/* NG */<ul class="navList"> <li class="navList__item"> <a class="navList__item__link" href=""></a> </li></ul>

/* OK */<ul class="navList"> <li class="navList__item"> <a class="navList__link" href=""></a> </li></ul>

冗長にならないようにする

クラスの命名

理由プレフィックスとモディファイアを認識しやすくするBEM を採用するとクラス名が冗長になるので少しでも短くするため

クラス名にはキャメルケースを使用し、プレフィックスとモディファイア以外でハイフンは使用しない

( 例 )/* NG */.c-ghost-btn--primary

/* OK */.c-ghostBtn--primay

ghostBtn がキャメルケースで記述されている

マルチクラス

理由CSS でで重複する記述が減らせるためファイル容量が減るためルールセットの再利用性があがるため保守性が向上するため

コンポーネント設計のアプローチはマルチクラスを採用（ @extend を使用したシングルクラス設計の場合は可）

スタイルの打ち消し

理由ファイル容量の節約のため

スタイルを打ち消さずにコンポーネントを定義する打ち消しが発生する場合、 1 つのルールに過剰なスタイルを追加しているので設計を見直す

( 例 )/* NG */.headline { font-size: 2rem; margin-bottom: 10px; border-bottom: 1px solid #333;}

.no-border { border: none;}

/* OK */.headline { font-size: 2rem; margin-bottom: 10px;}

.headline--border { border-bottom: 1px solid #333;}

絶対値

理由不要な CSS を減らせるため

柔軟に対応できるようにするため絶対値は原則使用しない

( 例 )/* NG */h1 { font-size: 2.4rem; line-height: 32px;}

.siteTitle { font-size: 3.6rem; line-height: 48px;}

/* OK */h1 { font-size: 2.4rem; line-height: 1.333;}

.siteTitle { font-size: 2.4rem;}

HTMLへの依存

理由HTML 内のタグが変更された際に CSS に影響がでないようにするため保守性が向上するため

可能な限り HTML に依存させないように定義する

( 例 )/* NG */<div class="contents"> <div class="wrap"> <h2>Contents Title</h2> <p>Contents の本文が入ります。</p> </div></div>

.contents .wrap h2 { font-size: 2.4rem;}

/* OK */<div class="contents"> <div class="wrap"> <h2 class="headline">Contents Title</h2> <p>Contents の本文が入ります。</p> </div></div>

.headline { font-size: 2.4rem;}

環境設定 CSS のルール

HTML のルール

HTML/CSS 共通ルールGit のルール

HTML/CSS 共通ルール

画像のルール

HTML/CSS の共通ルールHTML ファイル、 CSS ファイルの共通ルール

英数字のみを使用する

理由開く環境によっては、文字化けする可能性があるため

ファイル名には日本語を使用せず、英数字にする

機種依存文字の使用禁止

理由記号と同様、エラーを引き起こす原因と成り得るため

機種に依存した文字を使用するのを禁止する(GoogleChrome なら変換時に右側に△マークがつくもは使用しないようにする )

必ずアルファベットから始める

理由数字から開始している id ・ class 名は、認識されないため

必ずアルファベットからはじめ、数字から始めない

ファイル名のスペースを禁止

理由ファイルを正常に処理出来なくなる可能性があるため

ファイル名をつけるときにスペースの使用を禁止する( 動作はするので注意が必要 )

特定の文字を使用禁止

理由Windows でファイル名に使用することが出来ないため( その他の記号も使用をする際には注意が必要 )

「 \ 」 , 「 / 」 , 「 : 」 , 「 ? 」 , 「 < 」 , 「 > 」 , 「 | 」 ,「＄」上記のの文字の使用禁止

環境設定 CSS のルール

HTML のルール

HTML/CSS 共通ルールGit のルール

画像のルール

画像のルール

画像のルール画像ファイルの命名に一定のルールを与えることで、名前からその画像が何を示すのかを判断できるようにする

ディレクトリ共通で使い回す画像 → img ディレクトリ直下ページ固有の画像 → ページ名でフォルダを作成

画像における命名規則「種類」と「詳細」をアンダーバーでつなげる

種類 _ 詳細 . 拡張子( 例 )menu_contact.jpg

デバイスごとに画像を分けるデバイスごとに画像を別にする際は、デバイスを追加する

種類 _ 詳細 _番号 _ デバイス . 拡張子( 例 )menu_contact_pc.jpgmenu_contact_sp.jpg

種類を 6 つに分類bg : 背景btn : ボタンicon : アイコンtxt : テキストttl : タイトルimg : 画像

詳細種類に対して詳細な説明をするicon_arrow.png

複数単語を使用したい場合はキャメルケースでつなげるicon_arrowPrev.png

番号同じ用途の画像が複数あった場合に、番号を付けるicon_arrow_01.png

※svg にすることで 1 つの画像でまかなえる場合は svg を使用する

画像のパス表記

理由どの階層にあっても同じパスで指定できるため（インクルードしたファイルでもルート相対パスであれば問題なく表示される）

ルート相対パスを基本とする

( 例 )// NG<img src="../img/test.png"><img src="http://test.com/img/test.png">

// OK<img src="/img/test.png">

相対パスのほうが記述量が少ない

最後に

まとめ (余談 )• ルールは作ることより、浸透させることのほうが難しい• それでも項目一つ一つの認識を明文化することが大事• 一貫したルールを守って作業を進めることは、将来的な選択に多大な幸福をもたらしてくれる

• README はプロジェクト毎に管理をして、柔軟にルールは変更するべきである

参考文献• メンテナブル CSS

https://www.cyberagent.co.jp/techinfo/techreport/report/id=7926• Harry Roberts氏による CSSガイドライン

https://github.com/kiwanami/CSS-Guidelines• 「 Google HTML/CSS Style Guide 」を適当に和訳してみた」

http://re-dzine.net/2012/05/google-htmlcss-style-guide/• HTML5 日本語訳

http://momdo.github.io/html5/Overview.html• 新人コーダーに知っておいて欲しい命名規則の考え方 [ 画像・ ID ・ class 名 ]

http://html-coding.co.jp/knowhow/tips/naming-rule/• Jade

https://gist.github.com/japboy/5402844• こんな HTML と CSS のコーディング規約で書きたい

http://qiita.com/pugiemonn/items/964203782e1fcb3d02c3

多くの方々の知恵を参考とさせていただきました心より感謝いたします

• Code smells in CSShttp://article.enja.io/articles/code-smells-in-css.html

• CSS 設計の基礎を見直すhttp://gihyo.jp/dev/serial/01/js-foundation/0009

• 100年後も崩れない CSS勉強会 第 1 回「詳細度」http://pepabo.github.io/css/specificity/

• 100年後も崩れない CSS勉強会 第 2 回「コンポーネント」http://pepabo.github.io/css/component/

• [CSS] Object Oriented CSS を学んで綺麗なコードを書くhttp://www.yoheim.net/blog.php?q=20141201

• SMACSS 読んだhttp://chroma.hatenablog.com/entry/2013/07/22/120818

• BEM とは何か？https://github.com/juno/bem-methodology-ja/blob/master/definitions.md

• 使いやすい WordPress のための CSS のつくりかたhttp://www.slideshare.net/Toro_Unit/wordpresscss