一、習慣に合ったCSSの原則を書く
8202 ワード
英文原文:Principles of writing consistent,idiomatic CSS(原版)訳者:tslmy原文アドレス:https://github.com/necolas/idiomatic-css/blob/master/translations/zh-CN/README.md
以下のドキュメントでは、合理的なCSS開発スタイルガイドについて概説します.このガイドラインは、既存の、一般的な、協力的な文風を開発者に強く奨励します.独自のスタイルガイドを作成するために、いくつかのコンテンツを選択的に吸収する必要があります.
このドキュメントは更新され続け、新しいアイデアを提出することを歓迎します.どうぞご貢献ください.
共通原則 スペース 注記 フォーマット 名前 例 コード組織 構築および導入 お礼を言う
「成功したプロジェクトの一員として、自分のためにコードを書くのは悪い行為だということを意識することが重要です.何千人もの人があなたのコードを使っている場合は、自分の好みで自分の知恵を明らかにするのではなく、最も明確なコードを書く必要があります.」-Idan Gazitコードを早期に最適化することを考えないでください.まず、それらが読めることと理解できることを保証しなければなりません. どのコードライブラリにおいても、何人が参加し、貢献しても、すべてのコードは一人で作成したものと同じであるべきです. 一貫して認められたスタイルを厳格に実行します. 疑わしい場合は、既存の汎用的なモードが使用される.
プロジェクトのすべてのコードには、スタイルが1つしかないはずです.スペースの使用には、常に一貫性を保つ必要があります.スペースを使用して可読性を向上させます.インデント時にスペースとタブ(TAB記号とも呼ばれる)を混用しないでください. は、ソフトインデント(スペースを使用)と本物のタブの間で1つを選択し、常にこの選択を維持します.(スペースの使用を推奨) スペースを使用してインデントする場合は、インデントごとに使用するスペースの数を選択します.(推奨:4スペース) ヒント:エディタを[非表示のコンテンツを表示](Show Non-Visible Contents)に設定します.これにより、行末のスペースとインデントを必要としない空行のスペースをクリアし、コメントの汚染を避けることができます.
ヒント:スペースフォーマットを決定したら、EditorConfigファイル(または他の同じもの)を使用して、コードライブラリ間でこの基本的なスペース規則を維持できます.
良い注釈は非常に重要です.コンポーネントの動作方法、限界、構築方法を説明する時間を残してください.チームの他のメンバーに、共通でないコードや明らかでないコードの目的を推測させないでください.
注釈のスタイルは簡潔で、コードライブラリで統一されている必要があります.コメントをトピックの上に配置し、1行を独占します. は、80文字などの合理的な範囲内で各行の長さを制御する. 注釈を使用して、CSSコードを文字通り独立した部分に分割します. 注釈の大文字と小文字は、通常の文と同じであり、一致するテキストインデントを使用する必要があります.
ヒント:エディタを構成すると、ショートカットキーを指定して、一貫して認可されたコメントモードを出力できます.
最終的に選択されたコードスタイルは、読みやすく、明確に注釈しやすく、無意識にエラーを導入する可能性を最小限に抑え、有用なdiffとblameを生成することを保証しなければならない.複数のセレクタのルールセットにおいて、各個別のセレクタは1行を独占する. は、ルールセットの左カッコの前にスペースを保持します. 宣言ブロックにおいて、各宣言は1行を独占する. 各宣言の前に1つのインデントが保持されます. 各宣言のコロンの後にスペースを保持します. 宣言ブロックの最後の宣言については、最後のセミコロンは常に保持される. ルールセットの右括弧は、ルールセットの最初の文字と同じ列に保持されます. 各ルール・セットの間に空のローが保持されます.
スタイル宣言の順序は単一の原則を守らなければならない.私の傾向は、関連するプロパティを組み合わせ、レイアウト、背景、色などのプロパティよりも構造にとって重要なプロパティ(たとえば、位置決めやボックスモデル)を前に置くことです.
小型の開発団体は、関連する属性宣言(例えば、位置決めやボックスモデル)を並べたい場合があります.
大規模なチームは、アルファベット順にソートするのが好きかもしれません.これは便利で、メンテナンスが簡単です.
単一の宣言のみを含む多数の宣言ブロックでは、わずかに異なる単行フォーマットを使用できます.この場合、左括弧の後と右括弧の前にスペースを残す必要があります.
カンマで区切られた非常に長い属性値(グラデーションやシャドウの宣言など)は、複数行に配置できます.これにより、可読性が向上し、効率的なdiffが生成されやすくなります.この場合、複数のフォーマットを選択できます.以下に、1つのフォーマットを示します.
16進数値では、 単一引用符または二重引用符の選択は一貫しています. は、 できれば、
異なるCSS前処理は異なる特性、機能、文法を持っている.符号化習慣は、使用される前処理プログラムに従って拡張され、その特有の機能に適応しなければならない.SCSSを使用する際には以下のガイドラインを遵守することをお勧めします.は、ネストされた深さを1レベルに制限します.レベル2を超えるネストについては、再評価を与えます.これにより、あまりにも詳細なCSSセレクタが発生することを回避することができる. 大量のネスト規則を回避します.可読性が影響を受けると、中断します.20行以上のネストされたルールが表示されないようにすることをお勧めします. は、 可能であれば、 は、カスタム関数の名前の前に
自分をコンパイラやプリプロセッサとして見ないで、名前を付けるときはできるだけはっきりした意味のある名前を採用します.また、htmlファイルとcssファイルのコードについては、できるだけ一致した命名規則を採用します.
次に、上記の規則を含むコードの例を示します.
cssコードライブラリにとって、コードファイルをどのように組織するかは重要であり、特に大きなコードライブラリにとってより重要です.ここでは、組織コードのいくつかの推奨事項について説明します.論理的に異なるコードを分離する. 異なるコンポーネント(component)のcssは、できるだけ異なるcssファイル(buildフェーズでツールで統合できる) を使用します.プリプロセッサ(lessなど)が使用される場合、色、フォントなどの共通のスタイルコードを変数に抽象化します.
いずれのプロジェクトにもbuildのプロセスがあるはずです.この段階では、ツールを使用してコードを検出したり、テストしたり、圧縮したりすることができます.また、本番環境にバージョン番号付きのコードを用意することもできます.ここでgruntというツールをお勧めしますが、とてもいいと思います.
すべての対idiomaticに感謝します.jsが貢献したネットユーザー.
以下のドキュメントでは、合理的なCSS開発スタイルガイドについて概説します.このガイドラインは、既存の、一般的な、協力的な文風を開発者に強く奨励します.独自のスタイルガイドを作成するために、いくつかのコンテンツを選択的に吸収する必要があります.
このドキュメントは更新され続け、新しいアイデアを提出することを歓迎します.どうぞご貢献ください.
目次
1.共通の原則
「成功したプロジェクトの一員として、自分のためにコードを書くのは悪い行為だということを意識することが重要です.何千人もの人があなたのコードを使っている場合は、自分の好みで自分の知恵を明らかにするのではなく、最も明確なコードを書く必要があります.」-Idan Gazit
2.スペース
プロジェクトのすべてのコードには、スタイルが1つしかないはずです.スペースの使用には、常に一貫性を保つ必要があります.スペースを使用して可読性を向上させます.
ヒント:スペースフォーマットを決定したら、EditorConfigファイル(または他の同じもの)を使用して、コードライブラリ間でこの基本的なスペース規則を維持できます.
3.コメント
良い注釈は非常に重要です.コンポーネントの動作方法、限界、構築方法を説明する時間を残してください.チームの他のメンバーに、共通でないコードや明らかでないコードの目的を推測させないでください.
注釈のスタイルは簡潔で、コードライブラリで統一されている必要があります.
ヒント:エディタを構成すると、ショートカットキーを指定して、一貫して認可されたコメントモードを出力できます.
CSS例:
/* ==========================================================================
========================================================================== */
/*
========================================================================== */
/**
* “Doxygen ”
*
* , ,
* , , , 。
*
* 、 ,
* 。 , HTML 、
* 。
*
* @tag “tag” 。
*
* TODO: “‘ ’ ” 。 ,
* , 80 ( ) 40 (
* ) , ( “ * ” ) 。
*/
/* */
4.フォーマット
最終的に選択されたコードスタイルは、読みやすく、明確に注釈しやすく、無意識にエラーを導入する可能性を最小限に抑え、有用なdiffとblameを生成することを保証しなければならない.
.selector-1,
.selector-2,
.selector-3[type="text"] {
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
display: block;
font-family: helvetica, arial, sans-serif;
color: #333;
background: #fff;
background: linear-gradient(#fff, rgba(0, 0, 0, 0.8));
}
.selector-a,
.selector-b {
padding: 10px;
}
宣言順序
スタイル宣言の順序は単一の原則を守らなければならない.私の傾向は、関連するプロパティを組み合わせ、レイアウト、背景、色などのプロパティよりも構造にとって重要なプロパティ(たとえば、位置決めやボックスモデル)を前に置くことです.
小型の開発団体は、関連する属性宣言(例えば、位置決めやボックスモデル)を並べたい場合があります.
.selector {
/* Positioning */
position: absolute;
z-index: 10;
top: 0;
right: 0;
bottom: 0;
left: 0;
/* Display & Box Model */
display: inline-block;
overflow: hidden;
box-sizing: border-box;
width: 100px;
height: 100px;
padding: 10px;
border: 10px solid #333;
margin: 10px;
/* Other */
background: #000;
color: #fff;
font-family: sans-serif;
font-size: 16px;
text-align: right;
}
大規模なチームは、アルファベット順にソートするのが好きかもしれません.これは便利で、メンテナンスが簡単です.
例外及び微細オフセットの原則の場合
単一の宣言のみを含む多数の宣言ブロックでは、わずかに異なる単行フォーマットを使用できます.この場合、左括弧の後と右括弧の前にスペースを残す必要があります.
.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);
}
その他
#aaa
などの小文字が使用されます.content: ""
などの二重引用符を使用することをお勧めします.input[type="checkbox"]
のようなセレクタ内の属性値にも引用符を付けます.margin: 0
のように0に単位を加えないでください.プリプロセッシング:フォーマットに関する追加の考慮
異なるCSS前処理は異なる特性、機能、文法を持っている.符号化習慣は、使用される前処理プログラムに従って拡張され、その特有の機能に適応しなければならない.SCSSを使用する際には以下のガイドラインを遵守することをお勧めします.
@extend
文を宣言ブロックの最初の行に常に配置する.@include
文を宣言ブロックの上部に配置し、@extend
文の直後に配置する.x-
または他の形式のプレフィックスを付けることを考慮する.これにより、独自の関数とCSSの元の関数を混同したり、関数名がライブラリ関数と競合したりすることを回避できます..selector-1 {
@extend .other-rule;
@include clearfix();
@include box-sizing(border-box);
width: x-grid-unit(1);
// other declarations
}
5.命名
自分をコンパイラやプリプロセッサとして見ないで、名前を付けるときはできるだけはっきりした意味のある名前を採用します.また、htmlファイルとcssファイルのコードについては、できるだけ一致した命名規則を採用します.
/* */
.s-scr {
overflow: auto;
}
.cb {
background: #000;
}
/* */
.is-scrollable {
overflow: auto;
}
.column-body {
background: #000;
}
6.例
次に、上記の規則を含むコードの例を示します.
/* ==========================================================================
Grid layout
========================================================================== */
/**
* Column layout with horizontal scroll.
*
* This creates a single row of full-height, non-wrapping columns that can
* be browsed horizontally within their parent.
*
* Example HTML:
*
*
*
*
*
*
*/
/**
* Grid container
*
* Must only contain `.cell` children.
*
* 1. Remove inter-cell whitespace
* 2. Prevent inline-block cells wrapping
*/
.grid {
height: 100%;
font-size: 0; /* 1 */
white-space: nowrap; /* 2 */
}
/**
* Grid cells
*
* No explicit width by default. Extend with `.cell-n` classes.
*
* 1. Set the inter-cell spacing
* 2. Reset white-space inherited from `.grid`
* 3. Reset font-size inherited from `.grid`
*/
.cell {
position: relative;
display: inline-block;
overflow: hidden;
box-sizing: border-box;
height: 100%;
padding: 0 10px; /* 1 */
border: 2px solid #333;
vertical-align: top;
white-space: normal; /* 2 */
font-size: 16px; /* 3 */
}
/* Cell states */
.cell.is-animating {
background-color: #fffdec;
}
/* Cell dimensions
========================================================================== */
.cell-1 { width: 10%; }
.cell-2 { width: 20%; }
.cell-3 { width: 30%; }
.cell-4 { width: 40%; }
.cell-5 { width: 50%; }
/* Cell modifiers
========================================================================== */
.cell--detail,
.cell--important {
border-width: 4px;
}
7.コード組織
cssコードライブラリにとって、コードファイルをどのように組織するかは重要であり、特に大きなコードライブラリにとってより重要です.ここでは、組織コードのいくつかの推奨事項について説明します.
8.構築と導入
いずれのプロジェクトにもbuildのプロセスがあるはずです.この段階では、ツールを使用してコードを検出したり、テストしたり、圧縮したりすることができます.また、本番環境にバージョン番号付きのコードを用意することもできます.ここでgruntというツールをお勧めしますが、とてもいいと思います.
お礼を言う
すべての対idiomaticに感謝します.jsが貢献したネットユーザー.