前端代碼風格

文件名

均採用小寫方式， 以中劃線分隔, 若有複數結構時，採用複數命名法

• 目錄名：scripts,styles,images,data-models

• 文件名： example.js retina-sprites.css

Javascript

註釋

什麼時候使用

• 難於理解的代碼段

• 可能存在錯誤的代碼段

• 瀏覽器特殊的HACK代碼

• 想吐槽的產品邏輯, 合做同事

• 業務邏輯強相關的代碼

// 單行註釋斜槓後面要留有一個空格

/*
 * 多行註釋最少三行，註釋內容與星標前保留一個空格
 */
 
 var hello = '';        // 描述變量能夠這樣寫在變量右邊
 
/*
 * 描述方法（函數）必須使用多行描述
 * 若有必要能夠加上參數和返回值說明，參考 http://usejsdoc.org/
 * @param {Object} balabalabala
 * @return {Object} balabalabala
 */
 function foo() {
     // 描述下面代碼時作什麼的，方法第一行不須要留空格
     doSomething();
     
     // 描述下面代碼時作什麼的，上方須要留一個空行
     afterDoSomething();
     
     if (flag) {
         // 描述下面代碼時作什麼的，代碼塊的第一行也不須要留空格
         drive();
     }
 }

語法

• 使用四個空格的 soft tabs — 這是保證代碼在各類環境下顯示一致的惟一方式。

• 通常狀況下 有關鍵字的地方都要有空格

• 字符串使用單引號而不是雙引號：｀var str = 'hello world';｀

• 單行長度，理論上不要超過80列，不過若是編輯器開啓 soft wrap 的話能夠不考慮單行長度

• 接上一條，若是須要換行，存在操做符的狀況，必定在操做符後換行，而後換的行縮進4個空格

• 這裏要注意，若是是屢次換行的話就沒有必要繼續縮進了，好比說下面這種就是最佳格式。

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

建立Object對象

// Bad
var team = new Team();
team.title = "AlloyTeam";
team.count = 25;

// Good  
var team = {
    title: "AlloyTeam",        // 冒號後須要跟一個空格
    count: 25
};

建立Array對象

// 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 ];

構造函數

/**
 * 建立一個構造函數
 */
function Modal(options) {    // 函數名使用大寫字母開頭，駝峯式命名
    this.width = options.width;    // 屬性在構造函數體中定義
    this.height = options.height;
}

Modal.prototype.show = function() {    // 方法定義在原型鏈上
    // show
}

Modal.prototype.hide = function() {
    // hide
}

// 實例化對象
var modal = new Modal({
        width: 200,
        height: 300
    });

if 語法

// if else 先後留有空格，
if (flag) {

} else {

}

for 語法

// 普通for
var values = [ 1, 2, 3, 4, 5, 6, 7 ],
    i, len;
for (i=0, len=values.length; i<len; i++) {
    process(values[i]);
}

// for in, （通常狀況下不要用for in）
var prop;
for (prop in object) {
    // 注意這裏必定要有 hasOwnProperty 的判斷,不要把原型鏈上的屬性枚舉出來
    if (object.hasOwnProperty(prop)) {
        console.log("Property name is " + prop);
        console.log("Property value is " + object[prop]);
    }
}

switch 語法

// switch和括號之間有空格， case須要縮進， break以後跟下一個case中間留一個空行
switch (condition) {
    case "first":
        // code
        break;

    case "third":
        // code
        break;

    default:
    // code
}

// 沒有default的狀況須要註釋特別說明
switch(condition) {
    case "first":
        // code
        break;

    case "second":
        // code
        break;

    // no default
}

聲明

變量聲明

var _body = $(document.body); // 全局變量使用下劃線 _ 開頭
function foo() {
    var result,    // 一個代碼塊裏的變量聲明只用一個var
         length,    // 一個變量一行，行末跟註釋
         mainWrap;// 駝峯式命名法
         
}

常量聲明

使用全大寫字母＋下劃線的命名方式方式

var IMAGE_DOMAIN = 'WWW.XXX.COM';

函數聲明

• 函數聲明統一使用function命令進行聲明

// good
function foo() {        // 小括號前不須要空格，小括號與大括號間須要一個空格
    doSomething(); // 函數調用括號先後不須要空格
    return "hello world";
}

// bad
var foo = function() {
    return "hello world";
}

// bad
var foo = new Function(
    'return "hello world"'
);

• 當即執行函數的寫法, 最外層必須包一層括號

// Good
(function() {
    "use strict";    // 使用嚴格模式

    function doSomething() {
        // code
    }

    function doSomethingElse() {
        // code
    }

})();

空行

說明：下面代碼中的註釋處表明着實際代碼中的空行

function foo1() {
    
}
// 方法之間加空行
function foo2() {
    
}
// 邏輯塊與方法之間加空行增長可讀性
for (var i=0; i<10; i++) {
    
} 
// 邏輯塊之間加空行增長可讀性
if (flag) {
    
} else {
    
}
// 文件結尾留一個空行

雜項

• 只有字符串類型容許使用 == !=，如if(x == 'a') 其餘狀況一概用嚴格比較條件 === !==

• eval 非特殊業務， 禁用！！！

• with 非特殊業務， 禁用！！！

CSS

語法

• 使用組合選擇器時，保持每一個獨立的選擇器佔用一行。

• 爲了代碼的易讀性，在每一個聲明的左括號前增長一個空格。

• 聲明塊的右括號應該另起一行。

• 每條聲明 : 後應該插入一個空格。

• 每條聲明應該只佔用一行來保證錯誤報告更加準確。

• 全部聲明應該以分號結尾。雖然最後一條聲明後的分號是可選的，可是若是沒有他，你的代碼會更容易出錯。

• 逗號分隔的取值，都應該在逗號以後增長一個空格。好比說box-shadow

• 不要在顏色值 rgb() rgba() hsl() hsla()和 rect() 中增長空格

• 不要帶有取值前面沒必要要的 0 (好比，使用 .5 替代 0.5)。

• 全部的十六進制值都應該使用小寫字母，例如 #fff。由於小寫字母有更多樣的外形，在瀏覽文檔時，他們可以更輕鬆的被區分開來。

• 爲選擇器中的屬性取值添加引號，例如 input[type="text"]。 他們只在某些狀況下無關緊要，因此都使用引號能夠增長一致性。

• 不要爲 0 指明單位，好比使用 margin: 0; 而不是 margin: 0px;。

/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
    padding: 15px;
    margin: 0px 0px 15px;
    background-color: rgba(0, 0, 0, 0.5);
    box-shadow: 0 1px 2px #C0C0C0, inset 0 1px 0 #F8F8F8
}

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

聲明順序

相關的屬性聲明應該如下面的順序分組處理：

1. Positioning

2. Box model 盒模型

3. Typographic 排版

4. Visual 外觀

Positioning 處在第一位，由於他可使一個元素脫離正常文本流，而且覆蓋盒模型相關的樣式。盒模型緊跟其後，由於他決定了一個組件的大小和位置。

其餘屬性只在組件 內部 起做用或者不會對前面兩種狀況的結果產生影響，因此他們排在後面。

關於完整的屬性以及他們的順序，請參考 Recess

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

Class 命名

• 保持 Class 命名爲全小寫，可使用短劃線（不要使用下劃線和 camelCase 命名）。短劃線應該做爲相關類的天然間斷。(例如，.btn 和 .btn-danger)。

• 避免過分使用簡寫。.btn 能夠很好地描述 button，可是 .s 不能表明任何元素。

• 使用 .js-* classes 來表示行爲(相對於樣式)，可是不要在 CSS 中包含這些 classes。

/* Bad example */
.t { ... }
.red { ... }
.header { ... }

/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }

選擇器

• 使用 classes 而不是通用元素標籤來優化渲染性能。

• 避免在常常出現的組件中使用一些屬性選擇器 (例如，[class^="..."])。瀏覽器性能會受到這些狀況的影響。

• 減小選擇器的長度，每一個組合選擇器選擇器的條目應該儘可能控制在 3 個之內。

• 只在必要的狀況下使用後代選擇器 (例如，沒有使用帶前綴 classes 的狀況).

/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

不要使用 @import

與 <link> 標籤相比，@import 指令要慢不少，不光增長了額外的請求次數，還會致使不可預料的問題。替代辦法有如下幾種：

• 使用多個 <link> 元素

• 經過 Sass 或 Less 相似的 CSS 預處理器將多個 CSS 文件編譯爲一個文件

HTML

語法

• 用兩個空格來代替製表符（tab） -- 這是惟一能保證在全部環境下得到一致展示的方法。

• 在屬性上，使用雙引號，不要使用單引號。

• 不要在自動閉合標籤結尾處使用斜線 - HTML5 規範 指出他們是可選的。

• 不要忽略可選的關閉標籤（例如，</li> 和 </body>）。

• 嵌套的節點應該縮進（四個空格）。

字符編碼

經過明確聲明字符編碼，可以確保瀏覽器快速並容易的判斷頁面內容的渲染方式。這樣作的好處是，能夠避免在 HTML 中使用字符實體標記（character entity），從而所有與文檔編碼一致（通常採用 UTF-8 編碼）。

引入 CSS 和 JavaScript

根據 HTML5 規範, 一般在引入 CSS 和 JavaScript 時不須要指明 type，由於 text/css 和 text/javascript 分別是他們的默認值。

屬性順序

HTML 屬性應該按照特定的順序出現以保證易讀性。

• class

• id

• name

• data-*

• src, for, type, href, value , max-length, max, min, pattern

• placeholder, title, alt

• aria-*, role

• required, readonly, disabled

Classes 是爲高可複用組件設計的，理論上他們應處在第一位。Ids 更加具體並且應該儘可能少使用（例如, 頁內書籤），因此他們處在第二位。

不要用JavaScript 生成標籤

在 JavaScript 文件中生成標籤讓內容變得更難查找，更難編輯，性能更差。應該儘可能避免這種狀況的出現。

示例代碼

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <!-- External CSS -->
    <link rel="stylesheet" href="code-guide.css">
    <!-- In-document CSS -->
    <style>
      /* ... */
    </style>
  </head>
  <body>
    <a id="..." class="..." data-modal="toggle" href="#">
      Example link
    </a>
    <input class="form-control" type="text">
    <img src="..." alt="...">
    
    <!-- JavaScript -->
    <script src="code-guide.js"></script>
  </body>
</html>