Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
README.md

README.md

一貫性のあるCSSらしいCSSを書くための原則

以下の文書はCSS開発のための合理的なスタイルガイドの骨子です。 規範になるべきものではないし、私自身のスタイルの好みを他者のコードに押し付けるつもりは一切ありません。しかし、これらのガイドラインは現存する一般的で分別のあるパターンを利用することを推奨します。

このドキュメントは常に変わっていくものなので、新しいアイデアを常に求めています。ぜひアイデア等を投稿してください。

一貫性のあるCSSらしいCSSを書くための原則の英語版はこちらから

目次

  1. 一般原則
  2. ホワイトスペース(余白)
  3. コメント
  4. フォーマット
  5. 命名規則
  6. 実例
  7. 編成
  8. ビルドとデプロイ

謝辞

1. 一般原則

"成功を収めるプロジェクトをうまく管理することの一つが自分でコードを書いて実現する ということではない。もし多くの人があなたのコードを利用しているなら、仕様の 中にはあなたの好みではなく、最大限に明確なコードを書くべきである。" - Idan Gazit

  • どんなに多くの人が貢献したとしても、どのコードも一人で書いたようにする。
  • 同意の上のでのスタイルを厳格に守る。
  • もし悩むようであれば常に現存する共通のパターンを利用する。

2. ホワイトスペース(余白)

プロジェクト内全てのソースコードで1つのスタイルのみを利用すること。ホワイトスペース(余白)は常に一貫性を保つこと。そしてホワイトスペース(余白)を可読性を向上するために利用すること。

  • インデントにはタブ、スペースを絶対に混在させないこと
  • ソフトインデント(スペース)かタブのどちらかを選び、その選択を途中で変更しないこと(スペースを優先)
  • もしスペースを利用する場合にインデントに利用する文字数を決めること (4スペースを優先)

ヒント: 利用しているエディタにて“隠しキャラクターの表示”が出来る様に設定すること。これで行の最後のホワイトスペースを削除し、意図的ではない空行を削除し、無駄なコミットを避ける。

3. コメント

ソースコード上の詳細なコメントは非常に重要です。コンポーネントがどのように動作するのか、どんな制約があるのか、そしてどんな構成になっているかを説明すること。チーム内の他のメンバーが一般的でなく、明確でもないコードの目的を推測させることがないようにしてください。

コメントのスタイルはシンプルでかつソースコードベースの中で一貫性を保っている必要があります。

  • コメントは対象になるコンポーネントの上の行に配置すること。
  • コメントを宣言文の後に追加しないこと。
  • 折り返し行は分別のある最大行以内におさめること。例: 80文字
  • コメントを使ってCSSのコードを別々のセクションに分解すること。
  • コメントの文頭を大文字にし、テキストインデントに一貫性を持たせること。

ヒント: エディタの設定でショートカットなどを用いて承諾済みのコメントパターンを出力できるようにしておく。

CSSの例:

/* ==========================================================================
   セクションコメントブロック
   ========================================================================== */

/* サブ・セクションコメントブロック
   ========================================================================== */

/*
 * グループコメントブロック
 * 複数行になるドキュメントや説明の際に最適
 */

/* 基本コメント */

SCSSの例:

// ==========================================================================
// セクションコメントブロック
// ==========================================================================

// サブ・セクションコメントブロック
// ==========================================================================

//
// グループコメントブロック
// 複数行になるドキュメントや説明の際に最適
//

// 基本コメント

4. フォーマット

選択したコードフォーマットはコードが: 読みやすく、コメントが明確で、意図しないエラーを最低限に防ぎ、かつdiffやblameなどのコマンドの利点が活かせる形であること。

  1. 複数セレクタを持つルールセットの場合、セレクタを1行ずつ記述すること。
  2. ルールセットの開き中カッコの前に1スペースを入れること。
  3. 宣言ブロックないでは宣言を1行ずつ記述すること。
  4. 各宣言で1レベルのインデントを行うこと。
  5. 宣言文のコロンの後にに1スペースを入れること。
  6. 宣言ブロック内の最後の宣言文には常にセミコロンを追加すること。
  7. ルールセットの閉じ中括弧はルールセット内の1番始めの文字の位置に合わせること。
  8. ルールセットは空行で分けること。
.selector-1,
.selector-2,
.selector-3 {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
    display: block;
    color: #333;
    background: #fff;
}

宣言順

宣言の順番は1つの原則に従って並べること。私の場合は関連するプロパティ同士でグループ化し、構造的に重要なプロパティ(例: ポジションやボックスモデル)はタイポグラフィー、バックグランド、カラーのプロパティよりも前に宣言するようにしている。

.selector {
    position: relative;
    display: block;
    width: 50%;
    height: 100px;
    padding: 10px;
    border: 0;
    margin: 10px;
    color: #fff
    background: #000;
}

アルファベット順もよく使われるが欠点は関連するプロパティ同士を分断してしまう点。例えば、ポジションのオフセットをグループ化できないし、ボックスモデルのプロパティは宣言ブロック内でバラバラに宣言されることになってしまいます。

例外と少しの偏差

1行の宣言が数多くある場合、これまでと異なる1行フォーマットを利用することも可能です。この場合、中カッコの内側両端に1つのスペースを入れること。

.selector-1 { width: 10%; }
.selector-2 { width: 20%; }
.selector-3 { width: 30%; }

グラデーションやシャドウなどの長く、コンマで分割できるプロパティ値を持つ場合、diffをより有効活用するために複数ラインを利用しても構いません。様々なフォーマットが考えられますが、以下はその内の1つです。

.selector {
    box-shadow:
        1px 1px 1px #000,
        2px 2px 1px 1px #ccc inset;
    background-image:
        linear-gradient(#fff, #ccc),
        linear-gradient(#f3c, #4ec);
}

その他

  • hex値は小文字を利用すること。例: #aaa
  • シングル、ダブルクォートには一貫性を持つこと。推奨はダブルクォートです。例: content: ""
  • セレクタ内の属性値は常にクォートで囲むこと。例: input[type="checkbox"]
  • 可能な場合にはゼロになる値に対して単位指定を行わないこと。例: margin: 0

プリプロセッサ: 追加フォーマット

CSSプリプロセッサの特性、機能、シンタックスはツールによって全く異なります。規則は利用しているプリプロセッサの特性に併せて拡張してください。 以下のガイドラインはSassを対象としたものになります。

  • 入れ子は1レベルに止めること。2レベル以上の入れ子構造になる場合は再度コードを見直すこと。これによりCSSのセレクタが必要以上に詳細になるのを防ぎます。
  • 入れ子ルールを数多く利用しないこと。読みやすさに影響を与え始めるようであれば分割すること。入れ子ルール内に20以上のルールセットを置かないことを推奨します。
  • @extend文は宣言ブロック内の1番上に記述すること。
  • 可能な限り@includeを宣言ブロック内、@extendの下にグループ化すること
  • ネイティブCSSの機能とカスタムした機能との違いの混乱を避け、ライブラリからの関数との衝突を避けるためにカスタム関数にx-のようなプリフィックスを利用するか他のネームスペースをつけるようにすること。
.selector-1 {
    @extend .other-rule;
    @include clearfix();
    @include box-sizing(border-box);
    width: x-grid-unit(1);
    // other declarations
}

5. 命名規則

我々は人間コードコンパイラ、コンプレッサではないので、そのように振る舞う必要はありません。

HTMLのクラスは明確で熟慮された名前を使用すること。HTMLファイル、CSSファイル内の両方で理解しやすく、一貫性のある命名パターンを選ぶこと。

/* 悪い命名規則の例 */

.s-scr {
    overflow: auto;
}

.cb {
    background: #000;
}

/* よりよい命名規則の例 */

.is-scrollable {
    overflow: auto;
}

.column-body {
    background: #000;
}

6. 実例

様々な規則の例

/* ==========================================================================
   グリッドレイアウト
   ========================================================================== */

/*
 * HTML例:
 *
 * <div class="grid">
 *     <div class="cell cell-5"></div>
 *     <div class="cell cell-5"></div>
 * </div>
 */

.grid {
    overflow: visible;
    height: 100%;
    /* Prevent inline-block cells wrapping */
    white-space: nowrap;
    /* Remove inter-cell whitespace */
    font-size: 0;
}

.cell {
    box-sizing: border-box;
    position: relative;
    overflow: hidden;
    width: 20%;
    height: 100%;
    /* Set the inter-cell spacing */
    padding: 0 10px;
    border: 2px solid #333;
    vertical-align: top;
    /* Reset white-space */
    white-space: normal;
    /* Reset font-size */
    font-size: 16px;
}

/* Cellの状態 */

.cell.is-animating {
    background-color: #fffdec;
}

/* Cellのサイズ
   ========================================================================== */

.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }

/* Cellの修飾因子
   ========================================================================== */

.cell--detail,
.cell--important {
    border-width: 4px;
}

7. 編成

ソースコードの編成はどんなCSSコード内でも重要なパートになり、また巨大なコードベースの場合はさらに重要になります。

  • ソースコードは論理的にはっきり異なることがわかるように分割すること
  • コンポーネントの明白さを強めるために別ファイルにすること(ビルドステップで連結すること)
  • プリプロセッサを利用している場合、共通なコード、タイポグラフィー、色などを変数にしておくこと

8. ビルドとデプロイ

プロジェクトは常にソースコードの文法チェック、テスト、圧縮、プロダクションへの準備のためのバージョンコントロールの手法を持つべきです。 これらのタスクにはBen Alman氏によるgruntが優れたツールです。

謝辞

idiomatic.jsに貢献した皆さんに感謝します。idoomatic.jsはインスピレーションであり、引用もし、ガイドラインとしても活用しました。