英文原文：Principles of writing consistent, idiomatic CSS（原版）
譯者：tslmy
原文地址：
https://github.com/necolas/idiomatic-css/blob/master/translations/zh-CN/README.md

以下文檔將概述一個合理的CSS開發(fā)風(fēng)格指導(dǎo)。本指導(dǎo)文件強烈鼓勵開發(fā)者使用已經(jīng)存在了的嚷掠、常見的、合力的文風(fēng)荞驴。您應(yīng)該有選擇地吸納一些內(nèi)容來創(chuàng)造您自己的風(fēng)格指南不皆。

這個文檔將持續(xù)更新，歡迎提出新的想法熊楼。還請多多貢獻霹娄。

目錄

1. 通用原則
2. 空格
3. 注釋
4. 格式
5. 命名
6. 實例
7. 代碼組織
8. 構(gòu)建及部署

致謝

<a name="general-principles"></a>

1. 通用原則

“作為成功的項目的一員，很重要的一點是意識到只為自己寫代碼是很糟糕的行為鲫骗。如果將有成千上萬人使用你的代碼犬耻，那么你需要編寫最具明確性的代碼，而不是以自我的喜好來彰顯自己的智商执泰≌泶牛” - Idan Gazit

• 別想著過早地優(yōu)化代碼。先得保證它們可讀又可理解才行术吝。
• 在任何代碼庫中计济，無論有多少人參與及貢獻茸苇，所有代碼都應(yīng)該如同一個人編寫的一樣。
• 嚴格執(zhí)行一致認可的風(fēng)格沦寂。
• 如果有疑議学密，則使用現(xiàn)有的、通用的模式传藏。

2. 空格

在項目的所有代碼中腻暮，應(yīng)該只有一個風(fēng)格。在空格的使用上毯侦，必須始終保持一致哭靖。使用空格來提高可讀性。

• 永遠不要在縮進時混用空格和制表符（又稱TAB符號）叫惊。
• 在軟縮進（使用空格）和真正的制表符間選擇其一款青，并始終堅持這一選擇。（推薦使用空格）
• 如果使用空格進行縮進霍狰，選擇每個縮進所使用的空格數(shù)抡草。（推薦：4個空格）

提示：將編輯器配置為“顯示不可見內(nèi)容”。這使你可以清除行尾的空格和不需要縮進的空行里的空格蔗坯，同時可以避免對注釋的污染康震。

提示：確定好一種空格格式后，您可以用一個EditorConfig文件（或者其他相同的東西）來幫助在代碼庫之間維持這種基本的空格約定宾濒。

<a name="comments"></a>

3. 注釋

良好的注釋是非常重要的腿短。請留出時間來描述組件（component）的工作方式、局限性和構(gòu)建它們的方法绘梦。不要讓你的團隊其它成員來猜測一段不通用或不明顯的代碼的目的橘忱。

注釋的風(fēng)格應(yīng)當(dāng)簡潔，并在代碼庫中保持統(tǒng)一卸奉。

• 將注釋放在主題上方并獨占一行钝诚。
• 控制每行長度在合理的范圍內(nèi)，比如80個字符榄棵。
• 使用注釋從字面上將CSS代碼分隔為獨立的部分凝颇。
• 注釋的大小寫應(yīng)當(dāng)與普通句子相同，并且使用一致的文本縮進疹鳄。

提示：通過配置編輯器拧略，可以提供快捷鍵來輸出一致認可的注釋模式。

CSS示例：

/* ==========================================================================
   區(qū)塊代碼注釋
   ========================================================================== */

/* 次級區(qū)塊代碼注釋
   ========================================================================== */

/**
 * “Doxygen式注釋格式”的簡短介紹
 *
 * 較長的說明文本從這里開始瘪弓，這是這段文字的第一句話垫蛆，而且這句話還
 * 沒結(jié)束，過了好一會兒，我了個去終于結(jié)束了月褥，煩不煩啊弛随。
 *
 * 當(dāng)需要進行更細致的解釋說明、提供文檔文本時宁赤，較長的說明文本就很
 * 有用了。這種長長的說明文本栓票，可以包括示例HTML啦决左、鏈接啦等等其
 * 他你認為重要或者有用的東西。
 *
 * @tag 這是一個叫做“tag”的標(biāo)簽走贪。
 *
 * TODO: 這個“‘需做’陳述”描述了一個接下來要去做的小工作佛猛。這種文本，
 *   如果超長了的話坠狡，應(yīng)該在80個半角字符（如英文）或40個全角字符（
 *   如中文）后便換行继找，并（在“ * ”的基礎(chǔ)上）再在后面縮進兩個空格。
 */

/* 一般的注釋 */

4. 格式

最終選擇的代碼風(fēng)格必須保證：易于閱讀逃沿，易于清晰地注釋婴渡，最小化無意中引入錯誤的可能性，可生成有用的diff和blame凯亮。

1. 在多個選擇器的規(guī)則集中边臼，每個單獨的選擇器獨占一行。
2. 在規(guī)則集的左大括號前保留一個空格假消。
3. 在聲明塊中柠并，每個聲明獨占一行。
4. 每個聲明前保留一級縮進富拗。
5. 每個聲明的冒號后保留一個空格臼予。
6. 對于聲明塊的最后一個聲明，始終保留結(jié)束的分號啃沪。
7. 規(guī)則集的右大括號保持與該規(guī)則集的第一個字符在同一列粘拾。
8. 每個規(guī)則集之間保留一個空行。

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

聲明順序

樣式聲明的順序應(yīng)當(dāng)遵守一個單一的原則谅阿。我的傾向是將相關(guān)的屬性組合在一起半哟，并且將對結(jié)構(gòu)來說比較重要的屬性（如定位或者盒模型）放在前面，先于排版签餐、背景及顏色等屬性寓涨。

小型的開發(fā)團體，可能會想要把相關(guān)的屬性聲明（比如說定位和箱模型）擺在一起氯檐。

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

大型團隊戒良，則可能更喜歡按字母排序，因為這樣做起來很方便冠摄，而且維護起來很容易糯崎。

例外及細微偏移原則的情況

對于大量僅包含單條聲明的聲明塊几缭，可以使用一種略微不同的單行格式。在這種情況下沃呢，在左大括號之后及右大括號之前都應(yīng)該保留一個空格年栓。

.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队腐。

預(yù)處理：格式方面額外的考慮

不同的CSS預(yù)處理有著不同的特性、功能以及語法奏篙。編碼習(xí)慣應(yīng)當(dāng)根據(jù)使用的預(yù)處理程序進行擴展柴淘，以適應(yīng)其特有的功能。推薦在使用SCSS時遵守以下指導(dǎo)秘通。

• 將嵌套深度限制在1級为严。對于超過2級的嵌套，給予重新評估肺稀。這可以避免出現(xiàn)過于詳實的CSS選擇器第股。
• 避免大量的嵌套規(guī)則。當(dāng)可讀性受到影響時话原，將之打斷夕吻。推薦避免出現(xiàn)多于20行的嵌套規(guī)則出現(xiàn)。
• 始終將@extend語句放在聲明塊的第一行繁仁。
• 如果可以的話涉馅，將@include語句放在聲明塊的頂部，緊接著@extend語句的位置黄虱。
• 考慮在自定義函數(shù)的名字前加上x-或其它形式的前綴稚矿。這有助于避免將自己的函數(shù)和CSS的原生函數(shù)混淆，或函數(shù)命名與庫函數(shù)沖突。

.selector-1 {
    @extend .other-rule;
    @include clearfix();
    @include box-sizing(border-box);
    width: x-grid-unit(1);
    // other declarations
}

5. 命名

不要試著把自己當(dāng)作編譯器或者預(yù)處理器晤揣，因此命名的時候盡量采用清晰的桥爽、有意義的名字。另外昧识，對于html文件和css文件中的代碼钠四，盡量采用一致的命名規(guī)則。

/* 沒有意義的命名  */
.s-scr {
    overflow: auto;
}
.cb {
    background: #000;
}

/* 比較有意義的命名方式 */
.is-scrollable {
    overflow: auto;
}
.column-body {
    background: #000;
}

<a name="example"></a>

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

<a name="organization"></a>

7. 代碼組織

對于css代碼庫來說滞诺，如何組織代碼文件是很重要的形导，尤其對于那些很大的代碼庫顯得更加重要。這里介紹幾個組織代碼的建議：

• 邏輯上對不同的代碼進行分離习霹。
• 不同的組件(component)的css盡量用不同的css文件（可以在build階段用工具合并到一起）
• 如果用到了預(yù)處理器（比如less），把一些公共的樣式代碼抽象成變量炫隶，例如顏色淋叶，字體等等。

8. 構(gòu)建及部署

任何一個項目伪阶，都應(yīng)該有一個build的過程煞檩，在這個階段我們可以通過工具對代碼進行檢測，測試栅贴，壓縮等等斟湃，還可以為生產(chǎn)環(huán)境準(zhǔn)備好帶有版本號的代碼。在這里我推薦一下grunt這個工具檐薯，我感覺它很不錯凝赛。

<a name="acknowledgements"></a>

致謝

感謝所有對idiomatic.js作出貢獻的網(wǎng)友。