CSSコーディングスタイル
作成中です - Mitsuhiro Yoshida (トーク)
概要 Overview
範囲
このドキュメントではMoodleコードを扱う開発者のためのスタイルガイドラインを説明します。純粋にコードレイアウトのメカニズムおよびMoodleのための私たちの選択についてのみ説明します。
ゴール
一貫したコーディングスタイルはどのような開発プロジェクトにおいても重要であり、特に多くの開発者が関わる場合はなおさらです。標準的なスタイルではコードが読みやすく理解しやすいものとなるため、全体的な品質向上にもつながります。
私たちが目指す目標概要:
- 簡潔性
- 可読性
- ツールの利便性
便利なツール
私たちはコーディングスタイルへの適合性を確認するため、stylelintを使用しています。また、stylefmtはCSSを自動的に再フォーマットするために使用できます - 詳細はLintingをご覧ください。
ファイルネーミング
通常、CSSファイルはプラグイン内で
styles.css
というファイル名になります。
テーマのファイル名はテーマデザイナの希望に沿ったものにできますが、以下に従ってください:
- 小文字および「-」で単語を区切ること。
- 可能な限り簡潔にすること。
- 説明的であること。
- CSSファイルの場合はフォルダ、LESSファイルの場合は
style/
のフォルダに置くこと。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の値には (スタイルを上書きする場合を除いて) ショートハンドを使用してください。
- は使用しないでください。代替手段がない場合、あなたが上書きを試みるCSSに問題が生じる可能性があります。
!important
- ベンダ固有のプロパティ接頭辞は参照する一般的なプロパティの前に直接表示してください。
単位
- 許可される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等のように記述しないでください。
テキストの方向を強制する Forcing the text direction
Whilst
.dir-rtl
should not be used any more, we've added
.text-ltr
which allows developers to force the direction of the text to left-to-right. This is especially needed for forms fields like: URLs, OS level Folders paths & apps, theme hex colors, English DB field names, emails, English text, numbers, regular expression patterns, symbols, code snippets or configuration samples.
.dir-rtl
はもう使用すべきではありませんが、私たちは開発者がテキストの方向を左から右に強制できる
.text-ltr
を追加しました。これは特に次のようなフォームフィールドに必要です。URL、OSレベルのフォルダパスおよびアプリ、テーマの16進色、英語のDBフィールド名、メール、英語のテキスト、数字、正規表現パターン、記号、コードスニペット、設定サンプル等です。
LESS
LESS works like CSS with some extra features. It should follow the CSS guidelines.
変数 Variables
- They should use camelCase to follow Bootstrap 2 that is used in core.
- As for CSS selectors, use semantic names: names tell what this is instead of what should it look like.
- As Bootstrap 2 does, do not add the word "Color" to variables for _background_ or _border_ and their derivatives.
- Declaring new variables should be done sparingly, too many variables kill the purpose of using them. If you declare one, try to set its default value from another one.
- Do not declare more variables than necessary. E.g.: If the background color and border color are likely to always be the same, prefer one variable.
正しい Correct
@textColor: red;
@wellBackground: #ccc;
@tableBackground: blue;
@blockBackground: @wellBackground;
@calendarGroupEvent: #f90;
間違い Incorrect
@text-color: red;
@wellBackground: #ccc;
@tableBackgrounColor: blue;
@blockBackground: #ccc;
@calendarGroupEventBackground: #f90;
@calendarGroupEventBorder: #f90;
セレクタ Selectors
- Selectors should be encapsulated rather than duplicated.
正しい 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;
}
値およびプロパティ Values and properties
- Colours, font sizes, etc... should never be hardcoded. You should, where possible, use a variable instead.
- The use of 'mixins' is encouraged instead of duplicating values and properties.
正しい 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」 Themes Clean and More
Clean theme should, where possible, not contain any CSS or LESS content. More theme, in comparison, inherits CSS styles for the logo from Clean theme, but also contains a small amount of LESS as an example for when customising a theme. Both Clean and More inherit fully all the CSS from their parent theme 'Bootstrap Base'. Cleanテーマは可能な限りCSSまたはLESSのコンテンツを含まないようにしています。それに比べてMoreテーマはロゴのCSSスタイルをCleanテーマから継承していますが、テーマのカスタマイズ時の例として少量のLESSも含んでいます。CleanおよびMoreは親テーマである「Bootstrap Base」からすべてのCSSを完全に継承しています。
謝辞 Credits
This document was drawn from the following sources:
