✍

Code Guide by @AlloyTeam

Standards for developing flexible, durable, and sustainable HTML and CSS, and maintainable JavaScript javascript

經過分析github代碼庫總結出來的工程師代碼書寫習慣：GO!!! css

Golden rule

Enforce these, or your own, agreed upon guidelines at all times. Small or large, call out what's incorrect. For additions or contributions to this Code Guide, pleaseopen an issue on GitHub. html

Every line of code should appear to be written by a single person, no matter the number of contributors. html5

項目命名

項目名所有采用小寫方式，以中劃線分隔。好比： my-project-name java

目錄名

目錄名參照上一條規則,有複數結構時，要採用複數命名法，好比說： scripts, styles, images, data-models git

JavaScript文件命名

全部js文件名，多個單詞組成時，採用中劃線鏈接方式，好比說：帳號模型文件 account-model.js github

CSS，SCSS文件命名

多個單詞組成時，採用中劃線鏈接方式，好比說：retina-sprites.scss web

HTML文件命名

多個單詞組成時，採用中劃線鏈接方式，好比說: error-report.html express

HTML

語法

使用四個空格的 soft tabs — 這是保證代碼在各類環境下顯示一致的惟一方式。
嵌套的節點應該縮進（四個空格）。
在屬性上，使用雙引號，不要使用單引號。
不要在自動閉合標籤結尾處使用斜線 - HTML5 規範指出他們是可選的。
不要忽略可選的關閉標籤（例如，</li> 和</body>）。

<!DOCTYPE html> <html> <head> <title>Page title</title> </head> <body> <img src="images/company-logo.png" alt="Company"> <h1 class="hello-world">Hello, world!</h1> </body> </html>

HTML5 doctype

在每一個 HTML 頁面開頭使用這個簡單地 doctype 來啓用標準模式，使其每一個瀏覽器中儘量一致的展示。 bootstrap

雖然doctype不區分大小寫，可是按照慣例，doctype大寫關於html屬性，大寫仍是小寫的一片文章

<!DOCTYPE html> <html> <head> </head> </html>

Language attribute

From the HTML5 spec:

Authors are encouraged to specify a lang attribute on the root html element, giving the document's language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth.

Read more about the lang attribute in the spec.

Head to Sitepoint for a list of language codes.

Sitepoint只是給出了語言代碼的大類，好比說中文就只給出了ZH，可是沒有區分香港，臺灣，大陸等。而微軟給出的一份細分了zh-cn,zh-hk,zh-tw, Head to Microsoft for adetail list of language codes.

<html lang="en-us"> <!-- ... --> </html>

IE compatibility mode

Internet Explorer supports the use of a document compatibility <meta> tag to specify what version of IE the page should be rendered as. Unless circumstances require otherwise, it's most useful to instruct IE to use the latest supported mode with edge mode.

For more information, read this awesome Stack Overflow article.

不一樣doctype在不一樣瀏覽器下的不一樣渲染模式，詭異模式總結的很到位.

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

字符編碼

經過聲明一個明確的字符編碼，讓瀏覽器輕鬆、快速的肯定適合網頁內容的渲染方式。

<head> <meta charset="UTF-8"> </head>

引入 CSS 和 JavaScript

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

HTML5 規範連接

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

實用高於完美

儘可能遵循 HTML 標準和語義，可是不該該以浪費實用性做爲代價。任什麼時候候都要用盡可能小的複雜度和儘可能少的標籤來解決問題。

屬性順序

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

id
class
name
data-*
src, for, type, href
title, alt
aria-*, role

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

<a id="..." class="..." data-modal="toggle" href="#"> Example link </a> <input class="form-control" type="text"> <img src="..." alt="...">

Boolean 屬性

Boolean 屬性指不須要聲明取值的屬性。XHTML 須要每一個屬性聲明取值，可是 HTML5 並不須要。

瞭解更多內容，參考 WhatWG section on boolean attributes:

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

若是你必須爲屬性添加並不須要的取值，參照 WhatWG 的指引:

若是屬性存在，他的取值必須是空字符串或者 [...] 屬性的規範名稱，不要在首尾包含空白字符。

簡而言之，不要爲 Boolean 屬性添加取值。

<input type="text" disabled> <input type="checkbox" value="1" checked> <select> <option value="1" selected>1</option> </select>

減小標籤數量

在編寫 HTML 代碼時，須要儘可能避免多餘的父節點。不少時候，須要經過迭代和重構來使 HTML 變得更少。參考下面的示例:

<!-- Not so great --> <span class="avatar"> <img src="..."> </span> <!-- Better --> <img class="avatar" src="...">

JavaScript 生成標籤

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

CSS

語法

使用四個空格的 soft tabs — 這是保證代碼在各類環境下顯示一致的惟一方式。
使用組合選擇器時，保持每一個獨立的選擇器佔用一行。
爲了代碼的易讀性，在每一個聲明的左括號前增長一個空格。
聲明塊的右括號應該另起一行。
每條聲明 : 後應該插入一個空格。
每條聲明應該只佔用一行來保證錯誤報告更加準確。
全部聲明應該以分號結尾。雖然最後一條聲明後的分號是可選的，可是若是沒有他，你的代碼會更容易出錯。
逗號分隔的取值，都應該在逗號以後增長一個空格。好比說box-shadow
不要在顏色值 rgb() rgba() hsl() hsla()和 rect()中增長空格，而且不要帶有取值前面沒必要要的 0 (好比，使用 .5 替代 0.5)。This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space).
全部的十六進制值都應該使用小寫字母，例如 #fff。由於小寫字母有更多樣的外形，在瀏覽文檔時，他們可以更輕鬆的被區分開來。
儘量使用短的十六進制數值，例如使用 #fff 替代#ffffff。
爲選擇器中的屬性取值添加引號，例如input[type="text"]。他們只在某些狀況下無關緊要，因此都使用引號能夠增長一致性。
不要爲 0 指明單位，好比使用 margin: 0; 而不是margin: 0px;。

對這裏提到的規則有問題嗎？參考 Wikipedia 中的 CSS 語法部分。

/* 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 #CCC, inset 0 1px 0 #FFFFFF } /* 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 #ccc, inset 0 1px 0 #fff; }

聲明順序

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

Positioning
Box model 盒模型
Typographic 排版
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; }

// 爲了方便查閱， 我把Recess的order貼了一份過來, 引入時間2014-05-05 // css property order var order = [ 'position' , 'top' , 'right' , 'bottom' , 'left' , 'z-index' , 'display' , 'float' , 'width' , 'height' , 'max-width' , 'max-height' , 'min-width' , 'min-height' , 'padding' , 'padding-top' , 'padding-right' , 'padding-bottom' , 'padding-left' , 'margin' , 'margin-top' , 'margin-right' , 'margin-bottom' , 'margin-left' , 'margin-collapse' , 'margin-top-collapse' , 'margin-right-collapse' , 'margin-bottom-collapse' , 'margin-left-collapse' , 'overflow' , 'overflow-x' , 'overflow-y' , 'clip' , 'clear' , 'font' , 'font-family' , 'font-size' , 'font-smoothing' , 'osx-font-smoothing' , 'font-style' , 'font-weight' , 'hyphens' , 'src' , 'line-height' , 'letter-spacing' , 'word-spacing' , 'color' , 'text-align' , 'text-decoration' , 'text-indent' , 'text-overflow' , 'text-rendering' , 'text-size-adjust' , 'text-shadow' , 'text-transform' , 'word-break' , 'word-wrap' , 'white-space' , 'vertical-align' , 'list-style' , 'list-style-type' , 'list-style-position' , 'list-style-image' , 'pointer-events' , 'cursor' , 'background' , 'background-attachment' , 'background-color' , 'background-image' , 'background-position' , 'background-repeat' , 'background-size' , 'border' , 'border-collapse' , 'border-top' , 'border-right' , 'border-bottom' , 'border-left' , 'border-color' , 'border-image' , 'border-top-color' , 'border-right-color' , 'border-bottom-color' , 'border-left-color' , 'border-spacing' , 'border-style' , 'border-top-style' , 'border-right-style' , 'border-bottom-style' , 'border-left-style' , 'border-width' , 'border-top-width' , 'border-right-width' , 'border-bottom-width' , 'border-left-width' , 'border-radius' , 'border-top-right-radius' , 'border-bottom-right-radius' , 'border-bottom-left-radius' , 'border-top-left-radius' , 'border-radius-topright' , 'border-radius-bottomright' , 'border-radius-bottomleft' , 'border-radius-topleft' , 'content' , 'quotes' , 'outline' , 'outline-offset' , 'opacity' , 'filter' , 'visibility' , 'size' , 'zoom' , 'transform' , 'box-align' , 'box-flex' , 'box-orient' , 'box-pack' , 'box-shadow' , 'box-sizing' , 'table-layout' , 'animation' , 'animation-delay' , 'animation-duration' , 'animation-iteration-count' , 'animation-name' , 'animation-play-state' , 'animation-timing-function' , 'animation-fill-mode' , 'transition' , 'transition-delay' , 'transition-duration' , 'transition-property' , 'transition-timing-function' , 'background-clip' , 'backface-visibility' , 'resize' , 'appearance' , 'user-select' , 'interpolation-mode' , 'direction' , 'marks' , 'page' , 'set-link-source' , 'unicode-bidi' , 'speak' ]

Don't use @import

Compared to <link>s, @import is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach:

Use multiple <link> elements
Compile your CSS with a preprocessor like Sass or Less into a single file
Concatenate your CSS files with features provided in Rails, Jekyll, and other environments

For more information, read this article by Steve Souders.

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

媒體查詢位置

儘可能將媒體查詢的位置靠近他們相關的規則。不要將他們一塊兒放到一個獨立的樣式文件中，或者丟在文檔的最底部。這樣作只會讓你們之後更容易忘記他們。這裏是一個典型的案例。

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

前綴屬性

當使用廠商前綴屬性時，經過縮進使取值垂直對齊以便多行編輯。

在 Textmate 中，使用 Text → Edit Each Line in Selection (⌃⌘A)。在 Sublime Text 2 中，使用Selection → Add Previous Line (⌃⇧↑) 和 Selection → Add Next Line (⌃⇧↓)。

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

單條聲明的聲明塊

在一個聲明塊中只包含一條聲明的狀況下，爲了易讀性和快速編輯能夠考慮移除其中的換行。全部包含多條聲明的聲明塊應該分爲多行。

這樣作的關鍵因素是錯誤檢測 - 例如，一個 CSS 驗證程序顯示你在 183 行有一個語法錯誤,若是是一個單條聲明的行，那就是他了。在多個聲明的狀況下，你必須爲哪裏出錯了費下腦子。

/* Single declarations on one line */ .span1 { width: 60px; } .span2 { width: 140px; } .span3 { width: 220px; } /* Multiple declarations, one per line */ .sprite { display: inline-block; width: 16px; height: 15px; background-image: url(../img/sprite.png); } .icon { background-position: 0 0; } .icon-home { background-position: 0 -20px; } .icon-account { background-position: 0 -40px; }

屬性簡寫

堅持限制屬性取值簡寫的使用，屬性簡寫須要你必須顯式設置全部取值。常見的屬性簡寫濫用包括:

padding
margin
font
background
border
border-radius

大多數狀況下，咱們並不須要設置屬性簡寫中包含的全部值。例如，HTML 頭部只設置上下的 margin，因此若是須要，只設置這兩個值。過分使用屬性簡寫每每會致使更混亂的代碼，其中包含沒必要要的重寫和意想不到的反作用。

Mozilla Developer Network 有一篇對不熟悉屬性簡寫及其行爲的人來講很棒的關於 shorthand properties 的文章。

/* 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 中的嵌套

避免沒必要要的嵌套。能夠進行嵌套，不意味着你應該這樣作。只有在須要給父元素增長樣式而且同時存在多個子元素時才須要考慮嵌套。

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

代碼註釋

代碼是由人來編寫和維護的。保證你的代碼是描述性的，包含好的註釋，而且容易被他人理解。好的代碼註釋傳達上下文和目標。不要簡單地重申組件或者 class 名稱。

Be sure to write in complete sentences or larger comments and succinct phrases for general notes.

/* Bad example */ /* Modal header */ .modal-header { ... } /* Good example */ /* Wrapping element for .modal-title and .modal-close */ .modal-header { ... }

Class 命名

保持 Class 命名爲全小寫，可使用短劃線（不要使用下劃線和 camelCase 命名）。短劃線應該做爲相關類的天然間斷。(例如，.btn 和 .btn-danger)。
避免過分使用簡寫。.btn 能夠很好地描述 button，可是 .s 不能表明任何元素。
Class 的命名應該儘可能短，也要儘可能明確。
使用有意義的名稱；使用結構化或者做用目標相關，而不是抽象的名稱。
命名時使用最近的父節點或者父 class 做爲前綴。
使用 .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 { ... }

代碼組織

以組件爲單位組織代碼。
制定一個一致的註釋層級結構。
使用一致的空白來分割代碼塊，這樣作在查看大的文檔時更有優點。
當使用多個 CSS 文件時，經過組件而不是頁面來區分他們。頁面會被從新排列，而組件移動就能夠了。

/*  * Component section heading  */ .element { ... } /*  * Component section heading  *  * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.  */ .element { ... } /* Contextual sub-component or modifer */ .element-heading { ... }

編輯器配置

根據如下的設置來配置你的編輯器，來避免常見的代碼不一致和醜陋的 diffs。

使用四個空格的 soft-tabs。
在保存時刪除尾部的空白字符。
設置文件編碼爲 UTF-8。
在文件結尾添加一個空白行。

參照文檔，將這些設置應用到項目的 .editorconfig 文件。例如，Bootstrap 中的.editorconfig 文件。經過關於 EditorConfig 瞭解更多內容。

JavaScript

Indentation,分號,單行長度

一概使用4個空格
continuation-indentation 一樣適用4個空格，跟上一行對齊
Statement 以後一概以分號結束，不能夠省略
單行長度，理論上不要超過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"; }

空行

方法之間加
單行或多行註釋前加
邏輯塊之間加空行增長可讀性

變量命名

標準變量採用駝峯標識
使用的ID的地方必定全大寫
使用的URL的地方必定全大寫, 好比說 reportURL
涉及Android的，一概大寫第一個字母
涉及iOS的，一概小寫第一個，大寫後兩個字母
常量採用大寫字母，下劃線鏈接的方式
構造函數，大寫第一個字母

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

字符常量

通常狀況下統一使用 '' 單引號

null的使用場景

To initialize a variable that may later be assigned an object value
To compare against an initialized variable that may or may not have an object value
To pass into a function where an object is expected
To return from a function where an object is expected

不適合null的使用場景

Do not use null to test whether an argument was supplied
Do not test an uninitialized variable for the value null

undefined使用場景

永遠不要直接使用undefined進行變量判斷
使用字符串 "undefined" 對變量進行判斷

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

Object Literals

// Bad var team = new Team(); team.title = "AlloyTeam"; team.count = 25; // Good semi colon 採用 Followed by space 的形式 var team = { title: "AlloyTeam", count: 25 };

Array Literals

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

單行註釋

雙斜線後，必須跟註釋內容保留一個空格
可獨佔一行, 前邊不準有空行, 縮進與下一行代碼保持一致
可位於一個代碼行的末尾，注意這裏的格式

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

多行註釋格式

最少三行, 格式如右
前邊留空一行

什麼時候使用

難於理解的代碼段
可能存在錯誤的代碼段
瀏覽器特殊的HACK代碼
想吐槽的產品邏輯, 合做同事
業務邏輯強相關的代碼

/*  * 註釋內容與星標前保留一個空格  */

文檔註釋

各種標籤 @param @method 等參考http://usejsdoc.org/
格式如右

用在哪裏

All methods
All constructors
All objects with documented methods

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

括號對齊

標準示例括號先後有空格，花括號起始不另換行，結尾新起一行
花括號必需要，即便內容只有一行，決不容許右邊第二種狀況
涉及 if for while do...while try...catch...finally 的地方都必須使用花括號

// Good if (condition) { doSomething(); } if (condition) doSomething(); doSomethingElse();

if else else先後留有空格

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

switch

採用右邊的格式， switch和括號之間有空格， case須要縮進， break以後跟下一個case中間留一個blank line
花括號必需要，即便內容只有一行，決不容許右邊第二種情switch 的 falling through 必定要有註釋特別說明， no default 的狀況也須要註釋特別說明況

switch (condition) { case "first": // code break; case "third": // code break; default: // code } switch (condition) { // obvious fall through // 這裏爲啥JSHint默認就會放過，由於 case "first" 內無內容 case "first": case "second": // code break; case "third": // code /* falls through */ // 這裏爲啥要加這樣的註釋， 明確告知JSHint放過此處告警 default: // code } switch(condition) { case "first": // code break; case "second": // code break; // no default }

for

普通for循環, 分號後留有一個空格，判斷條件等內的操做符兩邊不留空格，前置條件若是有多個，逗號後留一個空格
for-in 必定要有 hasOwnProperty 的判斷，不然 JSLint 或者 JSHint 都會有一個 warn

var values = [ 1, 2, 3, 4, 5, 6, 7 ], i, len; for (i=0, len=values.length; i<len; i++) { process(values[i]); } var prop; for (prop in object) { // 注意這裏必定要有 hasOwnProperty 的判斷， 不然 JSLint 或者 JSHint 都會有一個 warn ！ if (object.hasOwnProperty(prop)) { console.log("Property name is " + prop); console.log("Property value is " + object[prop]); } }

變量聲明

全部函數內變量聲明放在函數內頭部，只使用一個 var(多了JSLint報錯)，一個變量一行，在行末跟註釋，註釋啊，註釋啊，親

function doSomethingWithItems(items) { var value = 10, // 註釋啊，註釋啊，親 result = value + 10, // 註釋啊，註釋啊 i, // 註釋啊，註釋啊，親 len; // 註釋啊，註釋啊，親 for (i=0, len=items.length; i < len; i++) { doSomething(items[i]); } }

函數聲明

必定先聲明再使用，不要利用 JavaScript engine的hoist特性, 違反了這個規則 JSLint 和 JSHint都會報 warn
function declaration 和 function expression 的不一樣，function expression 的（）先後必須有空格，而function declaration 在有函數名的時候不須要空格，沒有函數名的時候須要空格。
函數調用括號先後不須要空格
當即執行函數的寫法, 最外層必須包一層括號
"use strict" 決不容許全局使用，必須放在函數的第一行，能夠用自執行函數包含大的代碼段, 若是 "use strict" 在函數外使用， JSLint 和 JSHint 均會報錯

function doSomething(item) { // do something } var doSomething = function (item) { // do something } // Good doSomething(item); // Bad: Looks like a block statement doSomething (item); // Good var value = (function() { // function body return { message: "Hi" } }()); // Good (function() { "use strict"; function doSomething() { // code } function doSomethingElse() { // code } })();

雜項

徹底避免 == != 的使用，用嚴格比較條件 === !==
eval 非特殊業務，禁用！！！
with 非特殊業務，禁用！！！

Heavily inspired by Idiomatic CSS and the GitHub Styleguide. origin Project by @mdo. partly chinese translated by @zoomzhao. Made with all the love by @AlloyTeam.

✍

Code Guide by @AlloyTeam

Standards for developing flexible, durable, and sustainable HTML and CSS, and maintainable JavaScript

經過分析github代碼庫總結出來的工程師代碼書寫習慣：GO!!!

Naming Project

HTML

CSS

JavaScript

Golden rule

Enforce these, or your own, agreed upon guidelines at all times. Small or large, call out what's incorrect. For additions or contributions to this Code Guide, pleaseopen an issue on GitHub.

Every line of code should appear to be written by a single person, no matter the number of contributors.

項目命名

項目名所有采用小寫方式，以中劃線分隔。好比： my-project-name

目錄名

目錄名參照上一條規則,有複數結構時，要採用複數命名法，好比說： scripts, styles, images, data-models

JavaScript文件命名

全部js文件名，多個單詞組成時，採用中劃線鏈接方式，好比說：帳號模型文件 account-model.js

CSS，SCSS文件命名

多個單詞組成時，採用中劃線鏈接方式，好比說：retina-sprites.scss

HTML文件命名

多個單詞組成時，採用中劃線鏈接方式，好比說: error-report.html

HTML

語法

使用四個空格的 soft tabs — 這是保證代碼在各類環境下顯示一致的惟一方式。
嵌套的節點應該縮進（四個空格）。
在屬性上，使用雙引號，不要使用單引號。
不要在自動閉合標籤結尾處使用斜線 - HTML5 規範指出他們是可選的。
不要忽略可選的關閉標籤（例如，</li> 和</body>）。

<!DOCTYPE html> <html> <head> <title>Page title</title> </head> <body> <img src="images/company-logo.png" alt="Company"> <h1 class="hello-world">Hello, world!</h1> </body> </html>

HTML5 doctype

在每一個 HTML 頁面開頭使用這個簡單地 doctype 來啓用標準模式，使其每一個瀏覽器中儘量一致的展示。

雖然doctype不區分大小寫，可是按照慣例，doctype大寫關於html屬性，大寫仍是小寫的一片文章

<!DOCTYPE html> <html> <head> </head> </html>

Language attribute

From the HTML5 spec:

Authors are encouraged to specify a lang attribute on the root html element, giving the document's language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth.

Read more about the lang attribute in the spec.

Head to Sitepoint for a list of language codes.

<html lang="en-us"> <!-- ... --> </html>

IE compatibility mode

For more information, read this awesome Stack Overflow article.

不一樣doctype在不一樣瀏覽器下的不一樣渲染模式，詭異模式總結的很到位.

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

字符編碼

經過聲明一個明確的字符編碼，讓瀏覽器輕鬆、快速的肯定適合網頁內容的渲染方式。

<head> <meta charset="UTF-8"> </head>

引入 CSS 和 JavaScript

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

HTML5 規範連接

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

實用高於完美

儘可能遵循 HTML 標準和語義，可是不該該以浪費實用性做爲代價。任什麼時候候都要用盡可能小的複雜度和儘可能少的標籤來解決問題。

屬性順序

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

id
class
name
data-*
src, for, type, href
title, alt
aria-*, role

<a id="..." class="..." data-modal="toggle" href="#"> Example link </a> <input class="form-control" type="text"> <img src="..." alt="...">

Boolean 屬性

Boolean 屬性指不須要聲明取值的屬性。XHTML 須要每一個屬性聲明取值，可是 HTML5 並不須要。

瞭解更多內容，參考 WhatWG section on boolean attributes:

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

若是你必須爲屬性添加並不須要的取值，參照 WhatWG 的指引:

若是屬性存在，他的取值必須是空字符串或者 [...] 屬性的規範名稱，不要在首尾包含空白字符。

簡而言之，不要爲 Boolean 屬性添加取值。

<input type="text" disabled> <input type="checkbox" value="1" checked> <select> <option value="1" selected>1</option> </select>

減小標籤數量

在編寫 HTML 代碼時，須要儘可能避免多餘的父節點。不少時候，須要經過迭代和重構來使 HTML 變得更少。參考下面的示例:

<!-- Not so great --> <span class="avatar"> <img src="..."> </span> <!-- Better --> <img class="avatar" src="...">

JavaScript 生成標籤

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

CSS

語法

使用四個空格的 soft tabs — 這是保證代碼在各類環境下顯示一致的惟一方式。
使用組合選擇器時，保持每一個獨立的選擇器佔用一行。
爲了代碼的易讀性，在每一個聲明的左括號前增長一個空格。
聲明塊的右括號應該另起一行。
每條聲明 : 後應該插入一個空格。
每條聲明應該只佔用一行來保證錯誤報告更加準確。
全部聲明應該以分號結尾。雖然最後一條聲明後的分號是可選的，可是若是沒有他，你的代碼會更容易出錯。
逗號分隔的取值，都應該在逗號以後增長一個空格。好比說box-shadow
不要在顏色值 rgb() rgba() hsl() hsla()和 rect()中增長空格，而且不要帶有取值前面沒必要要的 0 (好比，使用 .5 替代 0.5)。This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space).
全部的十六進制值都應該使用小寫字母，例如 #fff。由於小寫字母有更多樣的外形，在瀏覽文檔時，他們可以更輕鬆的被區分開來。
儘量使用短的十六進制數值，例如使用 #fff 替代#ffffff。
爲選擇器中的屬性取值添加引號，例如input[type="text"]。他們只在某些狀況下無關緊要，因此都使用引號能夠增長一致性。
不要爲 0 指明單位，好比使用 margin: 0; 而不是margin: 0px;。

對這裏提到的規則有問題嗎？參考 Wikipedia 中的 CSS 語法部分。

/* 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 #CCC, inset 0 1px 0 #FFFFFF } /* 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 #ccc, inset 0 1px 0 #fff; }

聲明順序

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

Positioning
Box model 盒模型
Typographic 排版
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; }

// 爲了方便查閱， 我把Recess的order貼了一份過來, 引入時間2014-05-05 // css property order var order = [ 'position' , 'top' , 'right' , 'bottom' , 'left' , 'z-index' , 'display' , 'float' , 'width' , 'height' , 'max-width' , 'max-height' , 'min-width' , 'min-height' , 'padding' , 'padding-top' , 'padding-right' , 'padding-bottom' , 'padding-left' , 'margin' , 'margin-top' , 'margin-right' , 'margin-bottom' , 'margin-left' , 'margin-collapse' , 'margin-top-collapse' , 'margin-right-collapse' , 'margin-bottom-collapse' , 'margin-left-collapse' , 'overflow' , 'overflow-x' , 'overflow-y' , 'clip' , 'clear' , 'font' , 'font-family' , 'font-size' , 'font-smoothing' , 'osx-font-smoothing' , 'font-style' , 'font-weight' , 'hyphens' , 'src' , 'line-height' , 'letter-spacing' , 'word-spacing' , 'color' , 'text-align' , 'text-decoration' , 'text-indent' , 'text-overflow' , 'text-rendering' , 'text-size-adjust' , 'text-shadow' , 'text-transform' , 'word-break' , 'word-wrap' , 'white-space' , 'vertical-align' , 'list-style' , 'list-style-type' , 'list-style-position' , 'list-style-image' , 'pointer-events' , 'cursor' , 'background' , 'background-attachment' , 'background-color' , 'background-image' , 'background-position' , 'background-repeat' , 'background-size' , 'border' , 'border-collapse' , 'border-top' , 'border-right' , 'border-bottom' , 'border-left' , 'border-color' , 'border-image' , 'border-top-color' , 'border-right-color' , 'border-bottom-color' , 'border-left-color' , 'border-spacing' , 'border-style' , 'border-top-style' , 'border-right-style' , 'border-bottom-style' , 'border-left-style' , 'border-width' , 'border-top-width' , 'border-right-width' , 'border-bottom-width' , 'border-left-width' , 'border-radius' , 'border-top-right-radius' , 'border-bottom-right-radius' , 'border-bottom-left-radius' , 'border-top-left-radius' , 'border-radius-topright' , 'border-radius-bottomright' , 'border-radius-bottomleft' , 'border-radius-topleft' , 'content' , 'quotes' , 'outline' , 'outline-offset' , 'opacity' , 'filter' , 'visibility' , 'size' , 'zoom' , 'transform' , 'box-align' , 'box-flex' , 'box-orient' , 'box-pack' , 'box-shadow' , 'box-sizing' , 'table-layout' , 'animation' , 'animation-delay' , 'animation-duration' , 'animation-iteration-count' , 'animation-name' , 'animation-play-state' , 'animation-timing-function' , 'animation-fill-mode' , 'transition' , 'transition-delay' , 'transition-duration' , 'transition-property' , 'transition-timing-function' , 'background-clip' , 'backface-visibility' , 'resize' , 'appearance' , 'user-select' , 'interpolation-mode' , 'direction' , 'marks' , 'page' , 'set-link-source' , 'unicode-bidi' , 'speak' ]

Don't use @import

Compared to <link>s, @import is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach:

Use multiple <link> elements
Compile your CSS with a preprocessor like Sass or Less into a single file
Concatenate your CSS files with features provided in Rails, Jekyll, and other environments

For more information, read this article by Steve Souders.

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

媒體查詢位置

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

前綴屬性

當使用廠商前綴屬性時，經過縮進使取值垂直對齊以便多行編輯。

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

單條聲明的聲明塊

在一個聲明塊中只包含一條聲明的狀況下，爲了易讀性和快速編輯能夠考慮移除其中的換行。全部包含多條聲明的聲明塊應該分爲多行。

/* Single declarations on one line */ .span1 { width: 60px; } .span2 { width: 140px; } .span3 { width: 220px; } /* Multiple declarations, one per line */ .sprite { display: inline-block; width: 16px; height: 15px; background-image: url(../img/sprite.png); } .icon { background-position: 0 0; } .icon-home { background-position: 0 -20px; } .icon-account { background-position: 0 -40px; }

屬性簡寫

堅持限制屬性取值簡寫的使用，屬性簡寫須要你必須顯式設置全部取值。常見的屬性簡寫濫用包括:

padding
margin
font
background
border
border-radius

Mozilla Developer Network 有一篇對不熟悉屬性簡寫及其行爲的人來講很棒的關於 shorthand properties 的文章。

/* 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 中的嵌套

避免沒必要要的嵌套。能夠進行嵌套，不意味着你應該這樣作。只有在須要給父元素增長樣式而且同時存在多個子元素時才須要考慮嵌套。

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

代碼註釋

Be sure to write in complete sentences or larger comments and succinct phrases for general notes.

/* Bad example */ /* Modal header */ .modal-header { ... } /* Good example */ /* Wrapping element for .modal-title and .modal-close */ .modal-header { ... }

Class 命名

保持 Class 命名爲全小寫，可使用短劃線（不要使用下劃線和 camelCase 命名）。短劃線應該做爲相關類的天然間斷。(例如，.btn 和 .btn-danger)。
避免過分使用簡寫。.btn 能夠很好地描述 button，可是 .s 不能表明任何元素。
Class 的命名應該儘可能短，也要儘可能明確。
使用有意義的名稱；使用結構化或者做用目標相關，而不是抽象的名稱。
命名時使用最近的父節點或者父 class 做爲前綴。
使用 .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 { ... }

代碼組織

以組件爲單位組織代碼。
制定一個一致的註釋層級結構。
使用一致的空白來分割代碼塊，這樣作在查看大的文檔時更有優點。
當使用多個 CSS 文件時，經過組件而不是頁面來區分他們。頁面會被從新排列，而組件移動就能夠了。

/*  * Component section heading  */ .element { ... } /*  * Component section heading  *  * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.  */ .element { ... } /* Contextual sub-component or modifer */ .element-heading { ... }

編輯器配置

根據如下的設置來配置你的編輯器，來避免常見的代碼不一致和醜陋的 diffs。

使用四個空格的 soft-tabs。
在保存時刪除尾部的空白字符。
設置文件編碼爲 UTF-8。
在文件結尾添加一個空白行。

參照文檔，將這些設置應用到項目的 .editorconfig 文件。例如，Bootstrap 中的.editorconfig 文件。經過關於 EditorConfig 瞭解更多內容。

JavaScript

Indentation,分號,單行長度

一概使用4個空格
continuation-indentation 一樣適用4個空格，跟上一行對齊
Statement 以後一概以分號結束，不能夠省略
單行長度，理論上不要超過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"; }

空行

方法之間加
單行或多行註釋前加
邏輯塊之間加空行增長可讀性

變量命名

標準變量採用駝峯標識
使用的ID的地方必定全大寫
使用的URL的地方必定全大寫, 好比說 reportURL
涉及Android的，一概大寫第一個字母
涉及iOS的，一概小寫第一個，大寫後兩個字母
常量採用大寫字母，下劃線鏈接的方式
構造函數，大寫第一個字母

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

字符常量

通常狀況下統一使用 '' 單引號

null的使用場景

To initialize a variable that may later be assigned an object value
To compare against an initialized variable that may or may not have an object value
To pass into a function where an object is expected
To return from a function where an object is expected

不適合null的使用場景

Do not use null to test whether an argument was supplied
Do not test an uninitialized variable for the value null

undefined使用場景

永遠不要直接使用undefined進行變量判斷
使用字符串 "undefined" 對變量進行判斷

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

Object Literals

// Bad var team = new Team(); team.title = "AlloyTeam"; team.count = 25; // Good semi colon 採用 Followed by space 的形式 var team = { title: "AlloyTeam", count: 25 };

Array Literals

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

單行註釋

雙斜線後，必須跟註釋內容保留一個空格
可獨佔一行, 前邊不準有空行, 縮進與下一行代碼保持一致
可位於一個代碼行的末尾，注意這裏的格式

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

多行註釋格式

最少三行, 格式如右
前邊留空一行

什麼時候使用

難於理解的代碼段
可能存在錯誤的代碼段
瀏覽器特殊的HACK代碼
想吐槽的產品邏輯, 合做同事
業務邏輯強相關的代碼

/*  * 註釋內容與星標前保留一個空格  */

文檔註釋

各種標籤 @param @method 等參考http://usejsdoc.org/
格式如右

用在哪裏

All methods
All constructors
All objects with documented methods

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

括號對齊

標準示例括號先後有空格，花括號起始不另換行，結尾新起一行
花括號必需要，即便內容只有一行，決不容許右邊第二種狀況
涉及 if for while do...while try...catch...finally 的地方都必須使用花括號

// Good if (condition) { doSomething(); } if (condition) doSomething(); doSomethingElse();

if else else先後留有空格

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

switch

採用右邊的格式， switch和括號之間有空格， case須要縮進， break以後跟下一個case中間留一個blank line
花括號必需要，即便內容只有一行，決不容許右邊第二種情switch 的 falling through 必定要有註釋特別說明， no default 的狀況也須要註釋特別說明況

switch (condition) { case "first": // code break; case "third": // code break; default: // code } switch (condition) { // obvious fall through // 這裏爲啥JSHint默認就會放過，由於 case "first" 內無內容 case "first": case "second": // code break; case "third": // code /* falls through */ // 這裏爲啥要加這樣的註釋， 明確告知JSHint放過此處告警 default: // code } switch(condition) { case "first": // code break; case "second": // code break; // no default }

for

普通for循環, 分號後留有一個空格，判斷條件等內的操做符兩邊不留空格，前置條件若是有多個，逗號後留一個空格
for-in 必定要有 hasOwnProperty 的判斷，不然 JSLint 或者 JSHint 都會有一個 warn

var values = [ 1, 2, 3, 4, 5, 6, 7 ], i, len; for (i=0, len=values.length; i<len; i++) { process(values[i]); } var prop; for (prop in object) { // 注意這裏必定要有 hasOwnProperty 的判斷， 不然 JSLint 或者 JSHint 都會有一個 warn ！ if (object.hasOwnProperty(prop)) { console.log("Property name is " + prop); console.log("Property value is " + object[prop]); } }

變量聲明

全部函數內變量聲明放在函數內頭部，只使用一個 var(多了JSLint報錯)，一個變量一行，在行末跟註釋，註釋啊，註釋啊，親

function doSomethingWithItems(items) { var value = 10, // 註釋啊，註釋啊，親 result = value + 10, // 註釋啊，註釋啊 i, // 註釋啊，註釋啊，親 len; // 註釋啊，註釋啊，親 for (i=0, len=items.length; i < len; i++) { doSomething(items[i]); } }

函數聲明

必定先聲明再使用，不要利用 JavaScript engine的hoist特性, 違反了這個規則 JSLint 和 JSHint都會報 warn
function declaration 和 function expression 的不一樣，function expression 的（）先後必須有空格，而function declaration 在有函數名的時候不須要空格，沒有函數名的時候須要空格。
函數調用括號先後不須要空格
當即執行函數的寫法, 最外層必須包一層括號
"use strict" 決不容許全局使用，必須放在函數的第一行，能夠用自執行函數包含大的代碼段, 若是 "use strict" 在函數外使用， JSLint 和 JSHint 均會報錯

function doSomething(item) { // do something } var doSomething = function (item) { // do something } // Good doSomething(item); // Bad: Looks like a block statement doSomething (item); // Good var value = (function() { // function body return { message: "Hi" } }()); // Good (function() { "use strict"; function doSomething() { // code } function doSomethingElse() { // code } })();

雜項

徹底避免 == != 的使用，用嚴格比較條件 === !==
eval 非特殊業務，禁用！！！
with 非特殊業務，禁用！！！

Heavily inspired by Idiomatic CSS and the GitHub Styleguide. origin Project by @mdo. partly chinese translated by @zoomzhao. Made with all the love by @AlloyTeam.

騰訊前端代碼規範

Code Guide by @AlloyTeam

Table of contents

Golden rule

項目命名

目錄名

JavaScript文件命名

CSS，SCSS文件命名

HTML文件命名

HTML

語法

HTML5 doctype

Language attribute

IE compatibility mode

字符編碼

引入 CSS 和 JavaScript

HTML5 規範連接

實用高於完美

屬性順序

Boolean 屬性

減小標籤數量

JavaScript 生成標籤

CSS

語法

聲明順序

Don't use @import

媒體查詢位置

前綴屬性

單條聲明的聲明塊

屬性簡寫

LESS 和 SASS 中的嵌套

代碼註釋

Class 命名

選擇器

代碼組織

編輯器配置

JavaScript

Indentation,分號,單行長度

空行

變量命名

字符常量

null的使用場景

不適合null的使用場景

undefined使用場景

Object Literals

Array Literals

單行註釋

多行註釋格式

什麼時候使用

文檔註釋

用在哪裏

括號對齊

if else else先後留有空格

switch

for

變量聲明

函數聲明

雜項

Code Guide by @AlloyTeam

Table of contents

Golden rule

項目命名

目錄名

JavaScript文件命名

CSS，SCSS文件命名

HTML文件命名

HTML

語法

HTML5 doctype

Language attribute

IE compatibility mode

字符編碼

引入 CSS 和 JavaScript

HTML5 規範連接

實用高於完美

屬性順序

Boolean 屬性

減小標籤數量

JavaScript 生成標籤

CSS