CSSコーディングスタイル

概要 Overview

範囲

このドキュメントではMoodleコードを扱う開発者のためのスタイルガイドラインを説明します。純粋にコードレイアウトのメカニズムおよびMoodleのための私たちの選択についてのみ説明します。

ゴール

一貫したコーディングスタイルはどのような開発プロジェクトにおいても重要であり、特に多くの開発者が関わる場合はなおさらです。標準的なスタイルではコードが読みやすく理解しやすいものとなるため、全体的な品質向上にもつながります。

私たちが目指す目標概要:

• 簡潔性
• 可読性
• ツールの利便性

便利なツール

私たちはコーディングスタイルへの適合性を確認するため、stylelintを使用しています。また、stylefmtはCSSを自動的に再フォーマットするために使用できます - 詳細はLintingをご覧ください。

ファイルネーミング

通常、CSSファイルはプラグイン内で

styles.css

というファイル名になります。

テーマのファイル名はテーマデザイナの希望に沿ったものにできますが、以下に従ってください:

• 小文字および「-」で単語を区切ること。
• 可能な限り簡潔にすること。
• 説明的であること。
• CSSファイルの場合は

  style/
  

  フォルダ、LESSファイルの場合は

  less/
  

  のフォルダに置くこと。

ブロック

• 各セレクタは1行にまとめてください。セレクタのリストにカンマがある場合、カンマの後に改行を入れてください。
• プロパティと値のペアはそれぞれの行を4つの半角スペースでインデントして最後にセミコロンを付けてください。
• 閉じブレースは開始セレクタと同じレベルのインデントを使用する必要があります。
• ブロック間は1行空けてください。

正しい

@media only screen and (min-width: 768px) {
    .selector-one,
    .selector-two {
        color: #fff;
        background-color: #000;
    }
}

間違い

.selector_one, .selector_two { color: #fff; background-color: #000; }

セレクタ

• 常に小文字およびアンダースコアまたはハイフンを使用してください。ハイフンの使用を推奨します。
• 名称は簡単な英単語で構成されるべきです。
• 表現力を重視します。理解を深めるため、名称はできるだけ例示的にしてください。
• 意味のある名称の使用: 名称はどのように見えるのかではなく、これが何であるのか伝えてください。
• IDの使用は避けてください。IDを使用した場合、メンテナンスおよびオーバーライドが極めて困難になります。
• タグネームとクラスまたはIDを組み合わせて過度にルールを限定しないでください。

正しい

.selector_name {
    color: #fff;
}

.selector-name {
    color: #fff;
}

間違い

div#selName {
    color: #fff;
}

.Color-White {
    color: #fff;
}

プロパティおよび変数

• コロンおよび半角スペースで区切られている必要があります。これらは最小化しないでください。
• フォント名およびベンダ固有のプロパティを除き、半角小文字で記述してください。
• カラーコードには可能な限り小文字および略語を使用してください。
• カラーコードでHSLAまたはRGBAを使用する場合、常に16進数のフォールバックを提供してください。
• background, border, font, list-style, margin, paddingの値には (スタイルを上書きする場合を除いて) ショートハンドを使用してください。

• !important
  

  は使用しないでください。代替手段がない場合、あなたが上書きを試みるCSSに問題が生じる可能性があります。
• ベンダ固有のプロパティ接頭辞は参照する一般的なプロパティの前に直接表示してください。

単位

• 許可されるCSSの単位は次のとおりです: px, rem, em
• 値がゼロの場合、単位を宣言しないでください。

正しい

.something {
    margin-top: 0;
    font-size: 1.25em;
}

間違い

.something {
    margin-top: 0px;
    font-size: 1pt;
}

ドキュメンテーションおよびコメント

一般的なコーディングスタイルに従って、コメントは大文字で始まりピリオドで終えてください。

CSSファイルの先頭に入れたブロックスタイルのコメントでファイル内のルールの目的を説明してください。

/**
 * File base.css.
 * Contains base styles for theme basic.
 */

ブロックスタイルのコメントはCSSファイル内で特定のコンポーネント、ビュー、または機能に関するすべてのルールがあるセクションを示すためにも使用できます。

/**
 * SCORM Navigation Sidebar.
 */

1行のコメントを使用して単一ルールまたはルールの小さなサブセットについて他の開発者に詳細な情報を提供してください:

/* Required because YUI resets add a black border to all tables */

プログレッシブエンハンスメント

• フォールバックは常に提供されるべきです。例えば背景画像やグラデーションの背景色のフォールバックを提供する場合です。
• ベンダプリフィックスは対応ブラウザが接頭辞なしプロパティに対応していない場合のみ使用してください。
• 標準プロパティはベンダプリフィックスプロパティの後に来るようにしてください。

.selector {
    background-color: #444; /* Fallback for browsers that don't support gradients. */
    filter: progid:DXImageTransform.Microsoft.gradient(startColorStr='#444', EndColorStr='#999'); /* IE6-IE9. */
    background-image: -webkit-gradient(linear, left top, left bottom, from(#444), to(#999)); /* Safari 4+, Chrome. */
    background-image: -webkit-linear-gradient(top, #444, #999); /* Chrome 10+, Safari 5.1+, iOS 5+. */
    background-image: -moz-linear-gradient(top, #444, #999); /* Firefox 3.6. */
    background-image: -ms-linear-gradient(top, #444, #999); /* IE10. */
    background-image: -o-linear-gradient(top, #444, #999); /* Opera 11.10+. */
    background-image: linear-gradient(top, #444, #999); /* W3C Standard. */
}

ブラウザハック

• ブラウザ固有のハックは使用しないでください。Moodleではbody要素に追加されるクラスを使ってより適切なブラウザ固有のCSSを記述する方法を提供します。例えば以下のようになります:

.ie7 .forum-post {
    min-height: 1px;
}

• Moodle coreがサポートしていないブラウザのバージョン (例: Moodle 3.0のIE8) のハックを含める必要はありません。

プラグイン

プラグインではファイル名は以下のようにできます:

• styles.css (推奨)
• styles_<theme name>.css (非推奨、サードパーティプラグインのために予約)

必要最小限

プラグインはテキストのサイズ、色等、最小限のものしか定義しないでください。また、プラグインはテーマに属するものであり、簡単にテーマ設定できるようプラグインにハードコーディングされるべきではありません。もちろん、このためにはMoodleコアが要素にスタイルを与える再利用可能なクラスを提供する必要があります。Moodle 2.7ではデフォルトでBootstrap 2が採用されているため、そのクラスを使い始めることができますが、私たちは「bootstrapbase」を拡張しないテーマのために「base」等の賢明なフォールバックがあることを確認する必要があります。

右から左へ

Moodle 3.2以降、ほとんどの作業は開発者のために自動的に処理されるようになりました。

自動フリッピング

RTLCSS-PHPというツールの使用により、言語が右から左の場合にスタイルが自動的に反転されます。しかし、常にいくつかの例外があるため、CSSファイルに特別なコメントを追加してルールが反転しないようにする等が必要です。

以下、自動フリッピングの例です:

.hello-world {
    margin-left: 10px;
    /*rtl:ignore*/
    padding-left: 10px;

    background: url('logo.png') 0 0 no-repeat;
    /*rtl:raw:
    background-image: url('logo-rtl.png');
    */

    color: blue;
}

以下のように変更されます:

.hello-world {
    margin-right: 10px;
    padding-left: 10px;

    background: url('logo.png') 0 100% no-repeat;
    background-image: url('logo-rtl.png');

    color: blue;
}

特殊コメントの詳細に関してツールのドキュメントRTLCSS-PHPをご覧ください。

注意事項

注意すべき点は特別なコメントはファイルやルールブロックの最後であってはならないということです。ブロックまたはルールの前にないコメントはすべて無視されます。 言い換えれば: 現在、コメントは常に文の前になければならず、何も続かない場合は機能しません。

また、SCSSまたはLESSのコメントでは期待する効果が得られない場合が多いため、注意が必要です。SCSSおよびLESSを扱う場合、特別なRTLコメントは純粋なCSSの記述に添付するようにしてください:

@extend

, indented rules等のように記述しないでください。

テキストの方向を強制する

.dir-rtl

はもう使用すべきではありませんが、私たちは開発者がテキストの方向を左から右に強制できる

.text-ltr

を追加しました。これは特に次のようなフォームフィールドに必要です。URL、OSレベルのフォルダパスおよびアプリ、テーマの16進色、英語のDBフィールド名、メール、英語のテキスト、数字、正規表現パターン、記号、コードスニペット、設定サンプル等です。

LESS

LESS はCSS のように動作しますが、いくつかの追加機能があります。CSSのガイドラインに従ってください。

変数

• コアで使用されているBootstrap 2に準拠するため、camelCaseを使用する必要があります。
• CSS セレクタについてはセマンティックな名前を名称をしてください:「どうあるべきか」ではなく、「これは何であるか」を示す名称です。
• Bootstrap 2がそうであるように _background_ または _border_ 等の変数に「Color」という単語を追加しないでください。
• 新しい変数の宣言は控えめにすべきであり、あまりに多くの変数はそれらを使用する目的を殺してしまいます。もし、変数を宣言した場合、そのデフォルト値を別の変数に設定するように してください。
• 必要以上に変数を宣言しないでください。例) 背景色および枠線の色が常に同じになるような場合、1つの変数が望ましい。

正しい

@textColor: red;
@wellBackground: #ccc;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;

間違い

@text-color: red;
@wellBackground: #ccc;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;

セレクタ

• セレクタは重複させるのではなく、カプセル化すべきです。

正しい Correct

div {
    .something {
        color: red;
        a {
            color: blue;
        }
    }
    .something-else a {
        color: green;
    }
}

間違い Incorrect

div .something {
    color: red;
}
div .something a {
    color: blue;
}
div .something-else a {
    color: green;
}

値およびプロパティ

• 色、フォントサイズ等は決してハードコードしないでください。可能な限り変数を使用する必要があります。
• 値およびプロパティを重複して使用する代わりに「ミックスイン」(mixins) の使用を推奨します。

正しい Correct

.error {
    font-size: @fontSizeSmall;
    color: @errorText;
    padding: 1em;
    background-color: @errorBackground;
}
div .form-error {
    .error;
}

間違い Incorrect

.error {
    font-size: 12px;
    color: red;
    padding: 1em;
    background-color: white;
}
div .form-error {
    font-size: 12px;
    color: red;
    padding: 1em;
    background-color: white;
}

テーマ「Clean」および「More」

Cleanテーマは可能な限りCSSまたはLESSのコンテンツを含まないようにしています。それに比べてMoreテーマはロゴのCSSスタイルをCleanテーマから継承していますが、テーマのカスタマイズ時の例として少量のLESSも含んでいます。CleanおよびMoreは親テーマである「Bootstrap Base」からすべてのCSSを完全に継承しています。

謝辞

この文書は以下のソースを引用しています。

1. WordPress CSSコーディイングスタンダード

関連情報

• コーディングスタイル
• Javascriptコーディングスタイル
• コーディング