最后更新時(shí)間：2017-06-25

原始文章鏈接：https://github.com/bxm0927/web-code-standards

此項(xiàng)目用于記錄規(guī)范的、高可維護(hù)性的前端代碼，這是通過(guò)分析 Github 眾多前端代碼庫(kù)，總結(jié)出來(lái)的前端代碼書(shū)寫(xiě)規(guī)范。

目錄

  1. 前端普適性規(guī)范

  2. HTML 規(guī)范

  3. CSS 規(guī)范

  4. JS 規(guī)范

License

public domain, Just take it.

Thanks

@Ruan YiFeng: https://github.com/ruanyf

@materliu：https://materliu.github.io/code-guide

@hzlzh: https://github.com/hzlzh/Front-End-Standards

@tguide: http://tguide.qq.com/main/base.htm

前端普適性規(guī)范

黃金定律

永遠(yuǎn)遵循同一套編碼規(guī)范，可以是這里列出的，也可以是你自己總結(jié)的。如果你發(fā)現(xiàn)本
規(guī)范中有任何錯(cuò)誤，敬請(qǐng)指正。

不管有多少人共同參與同一項(xiàng)目，一定要確保每一行代碼都像是同一個(gè)人編寫(xiě)的。

項(xiàng)目命名

項(xiàng)目名全部采用小寫(xiě)方式，以中劃線分隔，禁止駝峰式命名。比如：my-project-name

文件命名

文件命名參照上一條規(guī)則，多個(gè)單詞組成時(shí)，采用中劃線連接方式，比如說(shuō): error-report.html

有復(fù)數(shù)結(jié)構(gòu)時(shí)，要采用復(fù)數(shù)命名法，比如說(shuō)： scripts, styles, images, data-models

文件名中只可由小寫(xiě)英文字母a~z、排序數(shù)字0~9或間隔符-組成，禁止包含特殊符號(hào)，比如空格、$等

為更好的表達(dá)語(yǔ)義，文件名使用英文名詞命名，或英文簡(jiǎn)寫(xiě)。

不允許命名帶有廣告等英文的單詞，例如ad,adv,adver,advertising，防止該模塊被瀏覽器當(dāng)成垃圾廣告過(guò)濾掉。任何文件的命名均如此。

  • index.shtml 引導(dǎo)頁(yè)&首頁(yè)

  • main.shtml 首頁(yè)

  • download.shtml 下載頁(yè)面

  • act.html 活動(dòng)列表頁(yè)面

  • video.html 視頻

  • cdkey.html CDKEY頁(yè)面

  • base.css 基本樣式

  • layout.css 框架布局

  • module.css 模塊樣式

  • global.css 全局樣式

  • font.css 字體樣式

  • index.css 首頁(yè)樣式

  • link.css 鏈接樣式

  • print.css 打印樣式

HTML 規(guī)范

語(yǔ)法

使用四個(gè)空格的縮進(jìn)，這是保證代碼在各種環(huán)境下顯示一致的唯一方式。

嵌套的節(jié)點(diǎn)應(yīng)該縮進(jìn)（四個(gè)空格）。

在屬性上，使用雙引號(hào)，不要使用單引號(hào)。

不要在自動(dòng)閉合標(biāo)簽結(jié)尾處使用斜線 - HTML5 規(guī)范 指出他們是可選的。

不要忽略可選的關(guān)閉標(biāo)簽（例如， 和 </body>）。

![](images/logo.png)

HTML5 doctype

在每個(gè) HTML 頁(yè)面開(kāi)頭使用這個(gè)簡(jiǎn)單地 doctype 來(lái)啟用標(biāo)準(zhǔn)模式，使其每個(gè)瀏覽器中盡可能一致的展現(xiàn)。

雖然doctype不區(qū)分大小寫(xiě)，但是按照慣例，doctype大寫(xiě)

<!DOCTYPE html>

語(yǔ)言屬性

<html lang="en"> </html>

字符編碼

通過(guò)明確聲明字符編碼，能夠確保瀏覽器快速并容易的判斷頁(yè)面內(nèi)容的渲染方式。這樣
做的好處是，可以避免在 HTML 中使用字符實(shí)體標(biāo)記（character entity），從而全部與
文檔編碼一致（一般采用 UTF-8 編碼）。

<meta charset="UTF-8">

IE 兼容模式

IE 支持通過(guò)特定的 <meta> 標(biāo)簽來(lái)確定繪制當(dāng)前頁(yè)面所應(yīng)該采用的 IE 版本。除非有強(qiáng)烈
的特殊需求，否則最好是設(shè)置為 edge mode，從而通知 IE 采用其所支持的最新的模
式。

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

響應(yīng)式

<meta name="viewport" content="width=device-width, initial-scale=1">

引入 CSS 和 JavaScript

根據(jù) HTML5 規(guī)范, 通常在引入 CSS 和 JavaScript 時(shí)不需要指明 type，因?yàn)?text/css 和 text/javascript 分別是他們的默認(rèn)值。

<!-- External CSS --> <link rel="stylesheet" href="code-guide.css"> <!-- In-document CSS --> <style>     /* ... */ </style> <!-- JavaScript --> <script src="code-guide.js"></script>

實(shí)用高于完美

盡量遵循 HTML 標(biāo)準(zhǔn)和語(yǔ)義，但是不應(yīng)該以浪費(fèi)實(shí)用性作為代價(jià)。任何時(shí)候都要用盡量小的復(fù)雜度和盡量少的標(biāo)簽來(lái)解決問(wèn)題。

減少標(biāo)簽數(shù)量

在編寫(xiě) HTML 代碼時(shí)，需要盡量避免多余的父節(jié)點(diǎn)。很多時(shí)候，需要通過(guò)迭代和重構(gòu)來(lái)使 HTML 變得更少。 參考下面的示例:

<!-- Not so great --> <span class="avatar">     ![](...) </span> <!-- Better --> ![](...)

屬性順序

HTML 屬性應(yīng)該按照特定的順序出現(xiàn)以保證易讀性。

  1. class

  2. id

  3. name

  4. data-*

  5. src, for, type, href, value , max-length, max, min, pattern

  6. placeholder, title, alt

  7. aria-*, role

  8. required, readonly, disabled

class 是為高可復(fù)用組件設(shè)計(jì)的，理論上他們應(yīng)處在第一位。id 更加具體而且應(yīng)該盡量少使用（例如, 頁(yè)內(nèi)書(shū)簽），所以他們處在第二位。

Boolean 屬性

Boolean 屬性指不需要聲明取值的屬性。XHTML 需要每個(gè)屬性聲明取值，但是 HTML5 并不需要。

一個(gè)元素中 Boolean 屬性的存在表示取值 true，不存在則表示取值 false。

簡(jiǎn)而言之，不要為 Boolean 屬性添加取值。

<input type="text" disabled>

JavaScript 生成標(biāo)簽

在 JavaScript 文件中生成標(biāo)簽讓內(nèi)容變得更難查找，更難編輯，性能更差。應(yīng)該盡量避免這種情況的出現(xiàn)。

CSS 規(guī)范

語(yǔ)法

使用四個(gè)空格的縮進(jìn)，這是保證代碼在各種環(huán)境下顯示一致的唯一方式。

使用組合選擇器時(shí)，保持每個(gè)獨(dú)立的選擇器占用一行。

為了代碼的易讀性，在每個(gè)聲明的左括號(hào)前增加一個(gè)空格。

聲明塊的右括號(hào)應(yīng)該另起一行。

每條聲明 : 后應(yīng)該插入一個(gè)空格。

每條聲明應(yīng)該只占用一行來(lái)保證錯(cuò)誤報(bào)告更加準(zhǔn)確。

所有聲明應(yīng)該以分號(hào)結(jié)尾。雖然最后一條聲明后的分號(hào)是可選的，但是如果沒(méi)有他，你的代碼會(huì)更容易出錯(cuò)。

逗號(hào)分隔的取值，都應(yīng)該在逗號(hào)之后增加一個(gè)空格。

不要在顏色值 rgb() rgba() hsl() hsla()和 rect() 中增加空格，并且不要帶有取值前面不必要的 0 (比如，使用 .5 替代 0.5)。

所有的十六進(jìn)制值都應(yīng)該使用小寫(xiě)字母，例如 #fff。因?yàn)樾?xiě)字母有更多樣的外形，在瀏覽文檔時(shí)，他們能夠更輕松的被區(qū)分開(kāi)來(lái)。

盡可能使用短的十六進(jìn)制數(shù)值，例如使用 #fff 替代 #ffffff。

為選擇器中的屬性取值添加引號(hào)，例如 input[type="text"]。 他們只在某些情況下可有可無(wú)，所以都使用引號(hào)可以增加一致性。

不要為 0 指明單位，比如使用 margin: 0; 而不是 margin: 0px;。

/* Bad CSS */ .selector, .selector-secondary, .selector[type=text] {     margin: 0px 0px 15px;     background-color: rgba(0, 0, 0, 0.5);     box-shadow: 0 1px 2px #CCC, inset 0 1px 0 #FFFFFF } /* Good CSS */ .selector, .selector-secondary, .selector[type="text"] {     margin-bottom: 15px;     background-color: rgba(0,0,0,.5);     box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff; }

聲明順序

相關(guān)的屬性聲明應(yīng)該以下面的順序分組處理：

  1. Positioning

  2. Box model 盒模型

  3. Typographic 排版

  4. Visual 外觀

Positioning 處在第一位，因?yàn)樗梢允挂粋€(gè)元素脫離正常文本流，并且覆蓋盒模型相關(guān)的樣式。盒模型緊跟其后，因?yàn)樗麤Q定了一個(gè)組件的大小和位置。

其他屬性只在組件內(nèi)部起作用或者不會(huì)對(duì)前面兩種情況的結(jié)果產(chǎn)生影響，所以他們排在后面。

.declaration-order {     /* Positioning */     position: absolute;     top: 0;     right: 0;     bottom: 0;     left: 0;     z-index: 100;     /* Box-model */     display: block;     float: right;     width: 100px;     height: 100px;     /* Typography */     font: normal 13px "Helvetica Neue", sans-serif;     line-height: 1.5;     color: #333;     text-align: center;     /* Visual */     background-color: #f5f5f5;     border: 1px solid #e5e5e5;     border-radius: 3px;     /* Misc */     opacity: 1; }

Don't use @import

與<link>相比，@import較慢，增加額外的頁(yè)面請(qǐng)求，并可能導(dǎo)致其他不可預(yù)見(jiàn)的問(wèn)題。

<!-- Use link elements --> <link rel="stylesheet" href="core.css"> <!-- Avoid @imports --> <style>     @import url("more.css"); </style>

媒體查詢位置

盡量將媒體查詢的位置靠近他們相關(guān)的規(guī)則。不要將他們一起放到一個(gè)獨(dú)立的樣式文件中，或者丟在文檔的最底部。這樣做只會(huì)讓大家以后更容易忘記他們。這里是一個(gè)典型的案例。

.element { ... } .element-avatar { ... } .element-selected { ... } @media (min-width: 480px) {     .element { ...}     .element-avatar { ... }     .element-selected { ... } }

前綴屬性

當(dāng)使用廠商前綴屬性時(shí)，通過(guò)縮進(jìn)使取值垂直對(duì)齊以便多行編輯。

/* Prefixed properties */ .selector {     -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);             box-shadow: 0 1px 2px rgba(0,0,0,.15); }

單條聲明的聲明塊

在一個(gè)聲明塊中只包含一條聲明的情況下，為了易讀性和快速編輯可以考慮移除其中的換行。所有包含多條聲明的聲明塊應(yīng)該分為多行。

這樣做的關(guān)鍵因素是錯(cuò)誤檢測(cè) - 例如，一個(gè) CSS 驗(yàn)證程序顯示你在 183 行有一個(gè)語(yǔ)法錯(cuò)誤,如果是一個(gè)單條聲明的行，那就是他了。在多個(gè)聲明的情況下，你必須為哪里出錯(cuò)了費(fèi)下腦子。

.span1 { width: 60px; } .span2 { width: 140px; } .span3 { width: 220px; }

屬性簡(jiǎn)寫(xiě)

盡量不使用屬性簡(jiǎn)寫(xiě)的方式，屬性簡(jiǎn)寫(xiě)需要你必須顯式設(shè)置所有取值。常見(jiàn)的屬性簡(jiǎn)寫(xiě)濫用包括:

  • padding

  • margin

  • font

  • background
    -border
    -border-radius

大多數(shù)情況下，我們并不需要設(shè)置屬性簡(jiǎn)寫(xiě)中包含的所有值。例如，HTML 頭部只設(shè)置上下的 margin，所以如果需要，只設(shè)置這兩個(gè)值。過(guò)度使用屬性簡(jiǎn)寫(xiě)往往會(huì)導(dǎo)致更混亂的代碼，其中包含不必要的重寫(xiě)和意想不到的副作用。

/* Bad example */ .element {     margin: 0 0 10px;     background: red;     background: url("image.jpg");     border-radius: 3px 3px 0 0; } /* Good example */ .element {     margin-bottom: 10px;     background-color: red;     background-image: url("image.jpg");     border-top-left-radius: 3px;     border-top-right-radius: 3px; }

Less 和 Sass 中的嵌套

避免不必要的嵌套?？梢赃M(jìn)行嵌套，不意味著你應(yīng)該這樣做。只有在需要給父元素增加樣式并且同時(shí)存在多個(gè)子元素時(shí)才需要考慮嵌套。

// Without nesting .table > thead > tr > th { … } .table > thead > tr > td { … } // With nesting .table > thead > tr {     > th { … }     > td { … } }

代碼注釋

代碼是由人來(lái)編寫(xiě)和維護(hù)的。保證你的代碼是描述性的，包含好的注釋，并且容易被他人理解。好的代碼注釋傳達(dá)上下文和目標(biāo)。不要簡(jiǎn)單地重申組件或者 class 名稱。

class 命名

保持 class 命名為全小寫(xiě)，可以使用短劃線（不要使用下劃線和 camelCase 命名）。短劃線應(yīng)該作為相關(guān)類的自然間斷。(例如，.btn 和 .btn-danger)。

避免過(guò)度使用簡(jiǎn)寫(xiě)。.btn 可以很好地描述 button，但是 .s 不能代表任何元素。

class 的命名應(yīng)該盡量短，也要盡量明確。

使用有意義的名稱；使用結(jié)構(gòu)化或者作用目標(biāo)相關(guān)，而不是抽象的名稱。

命名時(shí)使用最近的父節(jié)點(diǎn)或者父 class 作為前綴。

使用 .js-* 來(lái)表示行為(相對(duì)于樣式)，但是不要在 CSS 中包含這些 class。

選擇器

使用 class 而不是通用元素標(biāo)簽來(lái)優(yōu)化渲染性能。

避免在經(jīng)常出現(xiàn)的組件中使用一些屬性選擇器 (例如，[class^="..."])。瀏覽器性能會(huì)受到這些情況的影響。

減少選擇器的長(zhǎng)度，每個(gè)組合選擇器選擇器的條目應(yīng)該盡量控制在 3 個(gè)以內(nèi)。

只在必要的情況下使用后代選擇器 (例如，沒(méi)有使用帶前綴 classes 的情況).

代碼組織

以組件為單位組織代碼。

制定一個(gè)一致的注釋層級(jí)結(jié)構(gòu)。

使用一致的空白來(lái)分割代碼塊，這樣做在查看大的文檔時(shí)更有優(yōu)勢(shì)。

當(dāng)使用多個(gè) CSS 文件時(shí)，通過(guò)組件而不是頁(yè)面來(lái)區(qū)分他們。頁(yè)面會(huì)被重新排列，而組件移動(dòng)就可以了。

編輯器配置

根據(jù)以下的設(shè)置來(lái)配置你的編輯器，將這些設(shè)置應(yīng)用到項(xiàng)目的 .editorconfig 文件，來(lái)避免常見(jiàn)的代碼不一致和丑陋的 diffs。

  • 使用四個(gè)空格的縮進(jìn)。

  • 在保存時(shí)刪除尾部的空白字符。

  • 設(shè)置文件編碼為 UTF-8。

  • 在文件結(jié)尾添加一個(gè)空白行。

JS 規(guī)范

語(yǔ)法

使用四個(gè)空格的縮進(jìn)，這是保證代碼在各種環(huán)境下顯示一致的唯一方式。

聲明之后一律以分號(hào)結(jié)束， 不可以省略

完全避免 == != 的使用， 用嚴(yán)格比較條件 === !==

eval 非特殊情況， 禁用！?。?/p>

with 非特殊情況， 禁用?。?！

單行長(zhǎng)度，理論上不要超過(guò)80列，不過(guò)如果編輯器開(kāi)啟"自動(dòng)換行"的話可以不考慮單行長(zhǎng)度

接上一條，如果需要換行，存在操作符的情況，一定在操作符后換行，然后換的行縮進(jìn)4個(gè)空格

這里要注意，如果是多次換行的話就沒(méi)有必要繼續(xù)縮進(jìn)了，比如說(shuō)下面這種就是最佳格式。

if (typeof qqfind === "undefined" ||     typeof qqfind.cdnrejected === "undefined" ||     qqfind.cdnrejected !== true) {     url = "http://pub.idqqimg.com/qqfind/js/location4.js"; } else {     url = "http://find.qq.com/js/location4.js"; }

空行

方法之間加

單行或多行注釋前加

邏輯塊之間加空行增加可讀性

變量命名

標(biāo)準(zhǔn)變量采用駝峰標(biāo)識(shí)

使用的ID的地方一定全大寫(xiě)

使用的URL的地方一定全大寫(xiě), 比如說(shuō) reportURL

涉及Android的，一律大寫(xiě)第一個(gè)字母

涉及iOS的，一律小寫(xiě)第一個(gè)，大寫(xiě)后兩個(gè)字母

常量采用大寫(xiě)字母，下劃線連接的方式

構(gòu)造函數(shù)，大寫(xiě)第一個(gè)字母

var thisIsMyName; var goodID; var AndroidVersion; var iOSVersion; var MAX_COUNT = 10; function Person(name) {     this.name = name }

字符常量

一般情況下統(tǒng)一使用單引號(hào)

null的使用場(chǎng)景

初始化可能以后分配對(duì)象值的變量

與一個(gè)可能或可能沒(méi)有對(duì)象值的初始化變量進(jìn)行比較

傳入一個(gè)預(yù)期對(duì)象的函數(shù)

從預(yù)期對(duì)象的函數(shù)返回

不適合null的使用場(chǎng)景

不要使用null來(lái)測(cè)試是否提供參數(shù)

不要測(cè)試值為null的未初始化變量

undefined使用場(chǎng)景

永遠(yuǎn)不要直接使用undefined進(jìn)行變量判斷

使用字符串 "undefined" 對(duì)變量進(jìn)行判斷

// Bad var person; console.log(person === undefined);    //true // Good console.log(typeof person);    // "undefined"

對(duì)象字面量

// Bad var team = new Team(); team.title = "AlloyTeam"; team.count = 25; // Good var team = {     title: "AlloyTeam",     count: 25 };

數(shù)組聲明

// Bad var colors = new Array("red", "green", "blue"); var numbers = new Array(1, 2, 3, 4); // Good var colors = [ "red", "green", "blue" ]; var numbers = [ 1, 2, 3, 4 ];

單行注釋

雙斜線后，必須跟注釋內(nèi)容保留一個(gè)空格

與下一行代碼縮進(jìn)保持一致

可位于一個(gè)代碼行的末尾，雙斜線距離分號(hào)四個(gè)空格

// Good if (condition) {     // if you made it here, then all security checks passed     allowed(); } var zhangsan = "zhangsan";    // 雙斜線距離分號(hào)四個(gè)空格，雙斜線后始終保留一個(gè)空格

多行注釋格式

最少三行

前邊留空一行

/**  * 注釋內(nèi)容與星標(biāo)前保留一個(gè)空格  */

何時(shí)使用多行注釋格式

難于理解的代碼段

可能存在錯(cuò)誤的代碼段

瀏覽器特殊的HACK代碼

業(yè)務(wù)邏輯強(qiáng)相關(guān)的代碼

想吐槽的產(chǎn)品邏輯, 合作同事

文檔注釋

各類標(biāo)簽 @param @method 等 參考 http://usejsdoc.org/

用于：方法、構(gòu)造函數(shù)、對(duì)象

/**  * here boy, look here , here is girl  * @method lookGril  * @param {Object} balabalabala  * @return {Object} balabalabala  */

括號(hào)對(duì)齊

標(biāo)準(zhǔn)示例 括號(hào)前后有空格，花括號(hào)起始不另?yè)Q行，結(jié)尾新起一行

花括號(hào)必須要，即使內(nèi)容只有一行

涉及 if for while do...while try...catch...finally 的地方都必須使用花括號(hào)，即使內(nèi)容只有一行

if else 前后留有空格

if (condition) {     doSomething(); } else {     doSomethingElse(); }

switch

switch和括號(hào)之間有空格，case需要縮進(jìn)，break之后跟下一個(gè)case中間留一個(gè)空白行

花括號(hào)必須要， 即使內(nèi)容只有一行。

switch 的 falling through 一定要有注釋特別說(shuō)明，no default 的情況也需要注釋特別說(shuō)明況

switch (condition) {     case "first":         // code         break;     case "second":         // code         break;     default:     // code }

for

普通for循環(huán), 分號(hào)后留有一個(gè)空格， 判斷條件等內(nèi)的操作符兩邊不留空格

前置條件如果有多個(gè)，逗號(hào)后留一個(gè)空格

for-in 一定要有 hasOwnProperty 的判斷， 否則 JSLint 或者 JSHint 都會(huì)有一個(gè) warn

for (i=0, len=values.length; i<len; i++) {     pr

http://www.cnblogs.com/bxm0927/p/7077075.html