Go to Qiita Advent Calendar 2024 Top
LoginSignup
154
179

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 5 years have passed since last update.

@WalkerWalks(Koji Carvalho)

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

Last updated at Posted at 2016-01-15

概要

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

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

- 目的 -

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

- 参照 -
Google HTML/CSS Style Guide

ガイドライン運営ガイド

運営方法

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

例外

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

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

コーディング全般

エンコーディング

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](https://validator.w3.org)  
[CSS Validator: W3C](http://jigsaw.w3.org/css-validator/)
> 作業を提出する前にW3Cでエラーがないかチェックし予期せぬ問題が起きるを防ぐ

# HTMLコーディングガイド
## バージョン
HTML5を使用する。
> 現在のスタンダード。

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

```html
<!DOCTYPE html>
```

## 段落とヘッダー
`<p>`タグの中に`<h1>`などのヘッダーを使用しない。
> 用法が間違っている為、様々な問題の原因になる。

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

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

```

## リスト
シンプルなリストでは閉じタグを省略する。
> 省略しないとメニューを作成するときに予期しないマージンが入りレイアウトが崩れる。

```html
<ul>
    <li>item1
    <li>item2
</ul>
```

## 閉じてはいけないタグ
以下のタグは閉じてはいけない。
> 文法が間違っているので予期せぬ問題が起きる可能性がある。

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

## クラスはタグのすぐ隣に記述する
```html
<!--Recomended-->
<div class="header">
  <ul class="header_navi">
    <li>menu1
    <li>menu2
  </ul>
</div>
```

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

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

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

## プロパティ名の後にスペースを入れる
> 可読性を確保するため。

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

## カッコ開きは同じ行に
開きカッコの前には常に半角スペースを入れる
> 書き方を統一することで読みやすくする。

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

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

.selector
{
  propaty: value;
}
```

## セレクタ毎に行を変える
> 可読性確保のため。

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

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

## ルールの分離
ルールとルールの間には１行スペースを入れる
> 可読性確保のため

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

.class2 {
  margin: 0;
}

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

## セクションをコメントに記載する
> 可読性、メンテナンス性確保のため

```css
/* Header */

.header {
  margin: 5px 10px;
}

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

```
## !importantは使用しない
使用する必要があると感じたらCSSの設計を見直す
> メンテナンス性、拡張性が著しく低下する

## IDやクラス名を数字で始めない
文法が間違っているので認識されない。

```css
/* Not recommended */
.01class{
}
```

## 名前は英語を使う
内容が理解し難い場合は末尾に日本語でコメントを入れる。
> メンテナンス性の向上、コミュニケーションコストの低下

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

/* Not recommended */
.juuyou {
}
```

## 省略可能な場合は省略する
> 可読性、メンテナンス性のため

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

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

## 意味不明な名前は使用しない
IDやクラスに意味不明な名前や見た目を表す名前を付けない。
> メンテナンス性や拡張性を妨げる

```css
/* Recommended */
.selected {}


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

## 命名規則はBEMを使う
> ネーミングをルールを統一することで、コミュニケーションコストを削減できます。

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

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

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

###Block
ヘッダーやコンテンツカラムやメニューカラム,フッターと言った大きな塊を指します。
ブロックの中にブロックを作成することも出来ます。
その場合は親ブロックに依存しないように作成します。
###Element
Block内の要素がElementです。セパレータは"_"を使用します
###Modifier
エレメントまたはブロックの状態はModifierで設定します。セパレータは"-"を使用します。

**例：**

```html
<!-- 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>

```

## ネーミングルールと例
クラスの名前の作成は以下のルールに従います。

```css
.block
.block-state
.block_element
.block_element-state
```
上記の例では".header"と".nav"がブロック, ".header_logo"と".nav_item"がエレメント, ".nav_item-selected"が状態付きのエレメントになります。   
エレメントは"キー"と"値”を名前として書くこともあります。

```css
.nav_item-stateActive
```

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

```css
.rightMenu
.leftMenu
.topAdSpace
.bottomAdSpace
```

# 検証ガイド

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

を使用する。
> デスクトップ版、モバイル版にてトップシェアの物２つずつ

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

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
154
179

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?