概要

大学で行うプロジェクトの為にHTML/CSSコーディング規約を書いたのでその原文です。
オリジナルは"Gitbook/WalkerWalks"にて公開しています、項目の追加や修正はそちらにしていきますので、時間や興味が有る方はレビューやアイディアをいただけるとありがたいです。

背景：
大学のグラフィックデザイン科でのWebの開発におけるHTML/CSSのコーディングスタイルガイド。定石をまとめ書き方のルールを整備することで開発経験の浅いメンバーで行われるのプロジェクトの進行が円滑に進むように作成しています。

- 目的 -
1. コードの品質の安定
- 慣例・定石の例をまとめることで品質(拡張性, メンテナンス性, 可読性, バグの回避)を担保する。
1. コミュニケーションコストの削減
- ルールに沿った書き方をする事で連絡や質問事項を減らす。
1. 経験値の共有
- HTML/CSSの仕様上起きやすいミスを防ぐ

- 参照 -

Google HTML/CSS Style Guide

ガイドライン運営ガイド

運営方法

プロジェクトメンバ全てはガイドにをよく読み、疑問がある場合はリーダーに確認をする。
リーダーはメンバの疑問を解き、必要な場合は当メンバと共にガイドの改善策を考える。

例外

メンバーは極力スタイルガイドに従うがガイドがデメリットを生む場合に関してはガイドに従わない事をコメントに記す。尚、同じ例外が続く場合はガイドの変更を検討する

スタイルガイドの変更

スタイルガイドはプロジェクトの進行やメンバーのスキルにより、随時変更を加える事ができるが、変更は全メンバーにその都度通達しなければならないスタイルガイドに変更はを加える理由（現在の問題点)と変更内容を表記する。

コーディング全般

エンコーディング

BOMなしのUTF-8

HTML5の推奨エンコーディングで有るとともに、多くのCMSで採用されているエンコーディングで予期せぬ問題が起きにくい。

ルールの規定から外れた書き方をする場合で他の人が理解し難いと予想される部分にはコメントを残す。

インデント

スペースを２つ使う。

一般的な慣習によりスペースを使うひとが多いのでそれに従います。
参照: Popular Coding Convention on Github

<!--Recomended-->
<div>
  <ul>
    <li>item1
    <li>item2
  </ul>
</div>

/* Recomended */
.selector {
  propaty: value;
}

１行１要素

可読性を担保するため１行に書く要素は１つに留める

<!-- Recomended -->
<p>
    Hello <a href="#">World</a>
</p>
<ul>
    <li>itemA
    <li>itemB
</ul>

<!-- Not Recomended -->
<p>Hello <a href="#">World</a></p>
<ul>
    <li>itemA<li>itemB
</ul>

/* Recommended */
.selector {
  font-size: 1.2em;
  color: #A1A1A1;
}

/* Not recommended */
.selector {font-size: 1.2em;color:  #A1A1A1;}

大文字/小文字

タグ、ID、クラス、色コードなどの記述やには、キャメルケース使用の際の大文字を除き常に小文字を使う。(参照: wiki/キャメルケース)

慣例的に書きやすい為に全て小文字で書く。

<!-- Recommended -->
<a href="#">Home</a>

<!-- Not recommended -->
<A HREF="#">Home</A>

/* Recommended */
.selector {
  color: #a1a1a1;
}
/* camelCase */
.mySelector {
}

/* Not recommended */
.SELECTOR {
  COLOR: #A1A1A1;
}
.MYSELECTOR {
}

末尾スペース

プログラムによって問題が起こる場合があるので、末尾に空白を残さない。

<!-- Recomended -->
<p>Hello.

<!-- Not recomended -->
<p>Hello_

有効性をチェックする

HTML Validator: W3C

CSS Validator: W3C

作業を提出する前にW3Cでエラーがないかチェックし予期せぬ問題が起きるを防ぐ

HTMLコーディングガイド

バージョン

HTML5を使用する。

現在のスタンダード。

Doctype宣言をする

ブラウザによっては表示違いが出ることもあるため必ず宣言をする。

<!DOCTYPE html>

段落とヘッダー

<p>タグの中に<h1>などのヘッダーを使用しない。

用法が間違っている為、様々な問題の原因になる。

<!--Redomended-->
<h1>Header</h1>
<p>lorem ...</p>

<!--Not redomended-->
<p>
  <h1>Header</h1>
  lorem ...
</p>

閉じてはいけないタグ

以下のタグは閉じてはいけない。

文法が間違っているので予期せぬ問題が起きる可能性がある。

<!-- Recomended -->
<br>
<hr> 
<img>
<link>
<meta>
<input>

クラスはタグのすぐ隣に記述する

<!--Recomended-->
<div class="header">
  <ul class="header_navi">
    <li>menu1
    <li>menu2
  </ul>
</div>

スタイリングをしない

インラインスタイルやスタイリングタグを使用しない。

HTMLでのスタイリングを行うとCSSでの邪魔になるだけでなく構造が複雑になりメンテナンス性と可読性が著しく低下するため極力避ける。

<!--Not recomended-->
<p style="color: red">
<big>
<center>
<font>
<tt>

CSSコーディングスタイルガイド

プロパティ名の後にスペースを入れる

可読性を確保するため。

/* Recommended */
div {
  color: red;
  margin: 16px;
}
/* Not recommended */
div {
  color:red;
  margin:16px;
}

カッコ開きは同じ行に

開きカッコの前には常に半角スペースを入れる

書き方を統一することで読みやすくする。

/* Recomended */
.selector {
  propaty: value;
}

/* Not ecomended */
.selector{
  propaty: value;
}

.selector
{
  propaty: value;
}

セレクタ毎に行を変える

可読性確保のため。

/* Recomended */
.class1,
.class2,
.class3 {
  color: red;
}

/* Not ecomended */
.class1, .class2, .class3 {
  color: red;
}

ルールの分離

ルールとルールの間には１行スペースを入れる

可読性確保のため

/* Recomended */
.class1 {
  margin: 0;
}

.class2 {
  margin: 0;
}

/* Not ecomended */
.class1 {
  margin: 0;
}
.class2 {
  margin: 10px;
}

セクションをコメントに記載する

可読性、メンテナンス性確保のため

/* Header */

.header {
  margin: 5px 10px;
}

/* Content */
.content {
  margin: 0;
}

!importantは使用しない

使用する必要があると感じたらCSSの設計を見直す

メンテナンス性、拡張性が著しく低下する

IDやクラス名を数字で始めない

文法が間違っているので認識されない。

/* Not recommended */
.01class{
}

名前は英語を使う

内容が理解し難い場合は末尾に日本語でコメントを入れる。

メンテナンス性の向上、コミュニケーションコストの低下

/* Recommended */
.important {
}// 重要なもの

/* Not recommended */
.juuyou {
}

省略可能な場合は省略する

可読性、メンテナンス性のため

/* Recommended */
.mgs {}
.flg {}

/* Not recommended */
.message {}
.flag {}

意味不明な名前は使用しない

IDやクラスに意味不明な名前や見た目を表す名前を付けない。

メンテナンス性や拡張性を妨げる

/* Recommended */
.selected {}


/* Not recommended */
.red {}     //見た目を表す名前
.mx990 {}   //意味がわからない

命名規則はBEMを使う

ネーミングをルールを統一することで、コミュニケーションコストを削減できます。

追加:

idによるスタイル指定をしない

詳細度の計算やスタイル指定箇所の分散によって構造が複雑になりメンテナンス性が著しく低下する。

BEM

CSS設計手法の１つ。拡張,再利用がしやすくネーミングが分かりやすい特徴がある。
シンプルなHTML構造を保てるので小さなプロジェクトに採用しやすい。

考え方

BEMではページを以下の３つの形で捉えます。
- Block (塊)
- Element (要素)
- Modifier (状態）

Block

ヘッダーやコンテンツカラムやメニューカラム,フッターと言った大きな塊を指します。
ブロックの中にブロックを作成することも出来ます。
その場合は親ブロックに依存しないように作成します。

Element

Block内の要素がElementです。セパレータは"_"を使用します

Modifier

エレメントまたはブロックの状態はModifierで設定します。セパレータは"-"を使用します。

例：

<!-- header block -->
<div class="header">
  <!-- headerのelement "logo"-->
  <img class="header_logo" src="logo.png" alt="logo">
  <ul class="nav"><!-- nav block -->
    <li class="nav_item nav_item-selected">menu1
    <li class="nav_item">menu2
  </ul>
</div>

ネーミングルールと例

クラスの名前の作成は以下のルールに従います。

.block
.block-state
.block_element
.block_element-state

上記の例では".header"と".nav"がブロック, ".header_logo"と".nav_item"がエレメント, ".nav_item-selected"が状態付きのエレメントになります。

エレメントは"キー"と"値”を名前として書くこともあります。

.nav_item-stateActive

長い名前の書き方

ブロックやエレメントの名前に２つ以上の単語が入る場合もキャメルケースを使用します。

.rightMenu
.leftMenu
.topAdSpace
.bottomAdSpace

検証ガイド

検証用ブラウザ

表示検証は下記の最新版を使用する
- Internet Explorer
- Google Chrome
- Safari Mobile (iPhone)
- Android Browser (Android)

を使用する。

デスクトップ版、モバイル版にてトップシェアの物２つずつ

IEの検証について

使用可能な最新のもの使用しデベロッパモードを使用しIE9,10,11のレイアウト確認する。
(場合によってIE8も）

経験の浅いチームのためのHTML/CSSコーディング規約

概要