一貫した慣用的な CSS_html/css_WEB-ITnose を記述するための原則

英語原文: Principles of writing constant, idiomatic CSS (原文版) 翻訳者: tslmy 原文アドレス: https://github.com/necolas/idiomatic-css/blob/master/translations/zh-CN/ README. md

次のドキュメントは、合理的な CSS 開発スタイル ガイドの概要を示しています。このガイダンス文書は、開発者が既存の共通の相乗効果のある記述スタイルを使用することを強く推奨しています。独自のスタイル ガイドを作成するには、コンテンツを選択的に組み込む必要があります。

このドキュメントは継続的に更新され、新しいアイデアは歓迎されます。もっと貢献してください。

目次

1. 一般原則
2. スペース
3. コメント
4. 形式
5. 命名
6. 例
7. コードの構成
8. ビルドとデプロイ

ありがとうございます

1. 一般原則

プロジェクトの成功 コミュニティのメンバーとして、自分のためだけにコードを書くのは悪い行為であることを認識することが重要です。コードを何千人もの人が使用する場合は、自分のためではなく、できるだけ明示的なコードを書く必要があります。 IQ を示すには好みの設定を使用してください。」 - Idan Gazit

コードの最適化を時期尚早に考えないでください。まず、読みやすく理解できるものであることを確認する必要があります。
どのようなコードベースでも、参加し貢献する人が何人であっても、すべてのコードは 1 人によって書かれたように見える必要があります。
合意されたスタイルを厳密に実行します。
疑わしい場合は、既存の一般的なパターンを使用してください。

2. スペース

プロジェクトのすべてのコードにスタイルは 1 つだけ存在する必要があります。スペースの使用には常に一貫性を保つ必要があります。読みやすさを向上させるためにスペースを使用します。

• インデントするときにスペースとタブ (別名 TAB 記号) を決して 混ぜないでください。
ソフトインデント (スペースを使用) と実際のタブのどちらかを選択し、常にその選択に固執してください。 (スペースを推奨します)
インデントにスペースを使用する場合は、各インデントに使用するスペースの数を選択します。 (推奨: スペース 4 つ)

ヒント: 「非表示のコンテンツを表示する」ようにエディターを設定します。これにより、コメントの汚染を避けながら、末尾の空白やインデントを必要としない空行の空白をクリアできます。

ヒント: 空白の形式を決定したら、EditorConfig ファイル (または同等のもの) を使用して、コード ベース間でこの基本的な空白の規則を維持できます。

3. コメント

良いコメントは非常に重要です。コンポーネントがどのように機能するか、その制限事項、およびコンポーネントの構築方法について説明する時間を設けてください。一般的または明白ではないコード部分の目的を推測するのを、チームの他のメンバーに任せないでください。

コメントのスタイルは、コードベース全体で簡潔かつ一貫している必要があります。

コメントを件名の上の独立した行に配置します。
各行の長さは、80 文字などの妥当な範囲内で制御します。
コメントを使用して、文字通り CSS コードを独立した部分に分割します。
コメントは通常の文と同じように大文字と小文字を区別し、一貫したテキスト インデントを使用する必要があります。

ヒント: エディターを設定することで、合意されたコメント パターンを出力するためのショートカット キーを提供できます。

CSS の例:

/* ==========================================================================   区块代码注释   ========================================================================== *//* 次级区块代码注释   ========================================================================== *//** * “Doxygen式注释格式”的简短介绍 * * 较长的说明文本从这里开始，这是这段文字的第一句话，而且这句话还 * 没结束，过了好一会儿，我了个去终于结束了，烦不烦啊。 * * 当需要进行更细致的解释说明、提供文档文本时，较长的说明文本就很 * 有用了。这种长长的说明文本，可以包括示例HTML啦、链接啦等等其 * 他你认为重要或者有用的东西。 * * @tag 这是一个叫做“tag”的标签。 * * TODO: 这个“‘需做’陈述”描述了一个接下来要去做的小工作。这种文本， *   如果超长了的话，应该在80个半角字符（如英文）或40个全角字符（ *   如中文）后便换行，并（在“ * ”的基础上）再在后面缩进两个空格。 *//* 一般的注释 */

4. 形式

選択した最終的なコード スタイルは、読みやすく、明確にコメントしやすく、誤ってエラーが発生する可能性を最小限に抑え、有用な差分と非難を生成することを保証する必要があります。

複数のセレクターを含むルール セットでは、個々のセレクターがそれぞれ独自の行を占有します。
ルールセットの左中括弧の前にスペースを残します。
宣言ブロックでは、各宣言が独自の行にあります。
各ステートメントの前に 1 レベルのインデントを確保します。
ステートメント内の各コロンの後にはスペースを 1 つ残します。
宣言ブロック内の最後の宣言には、必ず終了セミコロンを付けてください。
ルール セットの右中括弧は、ルール セットの最初の文字と同じ列に残ります。
各ルールセットの間には空白行を残します。

.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;}

宣言の順序

スタイル宣言の順序は 1 つの原則に従う必要があります。私の傾向としては、関連するプロパティをグループ化し、構造上より重要なプロパティ (位置やボックス モデルなど) を、タイポグラフィ、背景、色などのプロパティよりも先に配置することです。

小規模な開発チームでは、関連するプロパティ宣言 (位置決めやボックス モデルなど) をまとめることもできます。

.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;}

大規模なチームでは、便利で保守が簡単なアルファベット順の並べ替えを好む場合があります。

例外とわずかなオフセットの原則

1 つの宣言のみを含む大きな宣言ブロックの場合は、わずかに異なる単一行形式を使用できます。この場合、左中括弧の後と右中括弧の前にスペースが必要です。

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

对于以逗号分隔并且非常长的属性值——例如一堆渐变或者阴影的声明——可以放在多行中，这有助于提高可读性，并易于生成有效的diff。这种情况下有多种格式可以选择，以下展示了一种格式。

.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"]。
• 如果可以的话，不要给0加上单位, 如margin: 0。

预处理：格式方面额外的考虑

不同的CSS预处理有着不同的特性、功能以及语法。编码习惯应当根据使用的预处理程序进行扩展，以适应其特有的功能。推荐在使用SCSS时遵守以下指导。

• 将嵌套深度限制在1级。对于超过2级的嵌套，给予重新评估。这可以避免出现过于详实的CSS选择器。
• 避免大量的嵌套规则。当可读性受到影响时，将之打断。推荐避免出现多于20行的嵌套规则出现。
• 始终将@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: * * <div class="grid"> *     <div class="cell cell-3"></div> *     <div class="cell cell-3"></div> *     <div class="cell cell-3"></div> * </div> *//** * 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代码库来说，如何组织代码文件是很重要的，尤其对于那些很大的代码库显得更加重要。这里介绍几个组织代码的建议：

• 逻辑上对不同的代码进行分离。
• 不同的组件(component)的css尽量用不同的css文件（可以在build阶段用工具合并到一起）
• 如果用到了预处理器（比如less），把一些公共的样式代码抽象成变量，例如颜色，字体等等。

8. 构建及部署

任何一个项目，都应该有一个build的过程，在这个阶段我们可以通过工具对代码进行检测，测试，压缩等等，还可以为生产环境准备好带有版本号的代码。在这里我推荐一下grunt这个工具，我感觉它很不错。

致谢

感谢所有对idiomatic.js作出贡献的网友。