Web技術中心程式碼規範

前言

軟體的長期價值直接源於其編碼質量。在它的整個生命週期裡，一個程式可能會被許多人閱讀或修改。如果一個程式可以清晰的展現出它的結構和特徵，那就能減少在以後對其進行修改時出錯的可能性，程式設計規範可以幫助程式設計師們增加程式的健壯性。基本所有的前端程式碼都是暴露給公眾的，所以我們更應該保證其質量。

規範理念

Any violation to this guide is allowed if it enhances readability.

所有的程式碼都要變成可供他人容易閱讀的。

--引用自Dojo Javascript 語法規範

規範詳解

JS命名規範

1. 必須使用 Tab 鍵進行程式碼縮排，以節約程式碼大小，建議設定編輯器的tab為4個空格的寬度（而不是4個空格）
2. 介面風格

結構	規則	例如
類	駝峰式	ModuleClass()
公有方法	混合式	getPosition()
公有變數	混合式	frameStyle
常量	大寫式	DEFAULT_FRAME_LAYOUT

1. 其他建議風格，非必要

結構	規則
公有方法和屬性	混合，例子：mixedCase
私有方法和屬性	混合，例子：_mixedCase
方法（method）引數	混合，例子：mixedCase
本地（local）變數	混合，例子：mixedCase

1. 所有語句結束後，必須使用 ; 號結束
2. 所有變數必須是有意義的英文，嚴厲禁止拼音
3. 變數允許使用公認英文縮寫
4. 類命名必須是駝峰式
5. 常量必須所有單詞大寫，並且每個單詞間加下劃線
6. 列舉型別時，列舉的命名必須有意義，列舉與列舉成員必須以駝峰式
7. 常量和列舉必須在最前端定義，merge 時注意，必須把常量與列舉定義的檔案放在檔案列表的第一位
8. 變數內的簡寫單詞如果在開頭則全小寫：xmlDocument，如果不在開頭則全大寫：loadXML！！！
9. "on"只能用作事件的命名
10. 函式開頭必須是有意義的動詞或動詞短語
11. 私有類的變數屬性成員 建議 使用混合式命名，並前面下下劃線
12. 臨時的全域性變數放到一個全域性的雜湊表裡，方便變量回收
13. 所有全域性變數必須初始化，儘量少用全域性變數
14. 大括號前面不能有換行符
15. 保留字以及特有的dom屬性不能作為變數名

特殊命名約定

1. 前面加 “is” 的變數名應該為布林值，亦可使用 “can” “has” “should”
2. 前面加 ”str” 的變數名應該為字串
3. 前面加 “arr” 的變數名應該為陣列
4. 前面加 “num” 或 “count” 的變數名應該為數字
5. “o” 作為區域性變數或引數，表示為Object
6. “e” 作為區域性變數或引數，表示為Element
7. “evt” 作為區域性變數或引數，表示為event
8. “err” 作為區域性變數或引數，表示為error
9. 重複變數建議使用 "i", "j", "k" （依次類推）等名稱的變數(全世界公認)
10. 能縮寫的單詞儘量縮寫
11. 避免產生令人誤解的布林值 isNotNumber isNan
12. 處理錯誤的變數，必須在後面跟著 “Error”
13. 初始化用的函式 必須使用 “init” 開頭，如果一個頁面只有初始化可以單獨使用 init()
14. 儘量做有意義的程式碼折行，不要讓一行程式碼過長。(HTML 字串除外)
15. 操作符 建議 使用空格隔開
16. 函式呼叫和方法 避免 使用空白
17. 逗號（,） 建議 使用空白隔開。
18. 不允許頻繁使用 previousSibling 和 nextSibling

詞法結構

1. 普通程式碼段應該看起來如下：

while(!isDone){         doSomething();         isDone = moreToDo(); }

1. 變數定義方法如下：

var a = null,    b = 1,    c = 0;

1. 函式定義方法如下：

var funcA = function(){    var a = 0;    ... }

1. if 語句應該看起來像這樣：

if(someCondition){         statements; }else if(someOtherCondition){         statements; }else{         statements; }

1. for 語句應該看起來像這樣：

for(initialization; condition; update){         statements; }

1. while 語句應該看起來像這樣：

while(!isDone){         doSomething();         isDone = moreToDo(); }

1. do ... while 語句應該看起來像這樣：

do{         statements; }while(condition);

1. switch 語句應該看起來像這樣：

switch(condition){          case "A":                   statements;          //註釋          case "B":                   statements;                   break;          default:                   statements;                   break; }

1. try ... catch 語句應該看起來像這樣：

try{         statements; }catch(ex){         statements; }finally{         statements; }

1. 單行的 if - else，while 或者 for 語句也必須加入括號：

if(condition){          statement; }while(condition){          statement; }for(intialization; condition; update){          statement; }

註釋規範(暫不實施，可略過)

1. 一些你不打算給其他人使用的函式，建議新增 @ignore 讓文件輸出時可以忽略這段註釋
2. 一些相關的功能相關的函式，建議加上@see Function 來對上下文做索引
3. 對於一些函式不建議或則需要注意的使用方法，必須加上 @deprecated作為提醒
4. 每個js檔案的檔案頭都必須包含 @fileoverview @author, 建議加上@version
5. 每個函式都必須使用JsDoc 來註釋他的用意
6. 每個帶引數的函式必須包含 @param
7. 每個有返回值的函式必須包含 @return
8. 建構函式必須加上 @constructor
9. 繼承函式建議加上 @base 表示其繼承於哪個類
10. 常用全域性變數建議使用 JsDoc 的註釋方式
11. 一般的變數及區域性變數才用 // 方式進行註釋，建議在需要做註釋的語句的上一行
12. 其他詳情請參考 JsDoc 註釋方法

其他

1. String 優化

迴圈體內的字串累加使用join方式。 例如:

var r= [];for (var i=0;i<100;i++){         r.push("hello");}var k= r.join("");

1. Switch 建議採用hash-table

switch 可以才用 Object代替 例如:

var a= {          "1":doAction1,          "2":doAction2,}function doAction1(){}function doAction2(){}a[1]();

1. 不建議使用eval

不推薦使用eval來執行指令碼。除非用來解釋已經確定安全的json資料。

1. 不要使用Function構造器。
2. 不要給setTimeout或者setInterval傳遞字串引數。
3. 注意 IE 的記憶體洩露問題
4. JavaScript程式碼獨立

Javascript不應該被包含在HTML檔案中,除非這是段特定只屬於此部分的程式碼。在HTML中的JavaScript程式碼會明顯增加檔案大小，而且也不能對其進行快取和壓縮。

CSS命名規範

1. id和class命名採用該版塊的英文單詞或組合命名，並第一個單詞小寫，第二個單詞首個字母大寫，如：newRelease（最新產品/new+Release)
2. CSS樣式表各區塊用註釋說明
3. 儘量使用英文命名原則
4. 不用加中槓
5. 儘量不縮寫，除非一看就明白的單詞

經過組員激烈的討論後，大家都比較偏向的命名方法如下：

ID：統一採用駝峰式 ：　單字之間不以空格斷開（例：camel case）或連線號（-，例：camel-case）、底線（_，例：camel_case）連結，

Class 命名法：駝峰式或下劃線

常見的CSS命名規則如下：

主要的 mian.css

模組 module.css

基本共用 base.css

佈局，版面 layout.css

主題 themes.css

專欄 columns.css

文字 font.css

表單 forms.css

補丁 mend.css

列印 print.css

頭：header

內容：content/container

尾：footer

導航：nav

側欄：sidebar

欄目：column

頁面外圍控制整體佈局寬度：wrapper

左右中：left right center

登入條：loginbar

標誌：logo

廣告：banner

頁面主體：main

熱點：hot

新聞：news

下載：download

子導航：subnav

選單：menu

子選單：submenu

搜尋：search

友情連結：friendlink

頁尾：footer

版權：copyright

滾動：scroll

內容：content

標籤頁：tab

文章列表：list

提示資訊：msg

小技巧：tips

欄目標題：title

加入：joinus

指南：guild

服務：service

註冊：regsiter

狀態：status

投票：vote

合作伙伴：partner

(二)註釋的寫法:

/* Footer */

內容區

/* End Footer */

(三)id的命名:

(1)頁面結構

容器: container

頁頭：header

內容：content/container

頁面主體：main

頁尾：footer

導航：nav

側欄：sidebar

欄目：column

頁面外圍控制整體佈局寬度：wrapper

左右中：left right center

(2)導航

導航：nav

主導航：mainbav

子導航：subnav

頂導航：topnav

邊導航：sidebar

左導航：leftsidebar

右導航：rightsidebar

選單：menu

子選單：submenu

標題: title

摘要: summary

(3)功能

標誌：logo

廣告：banner

登陸：login

登入條：loginbar

註冊：regsiter

搜尋：search

功能區：shop

標題：title

加入：joinus

狀態：status

按鈕：btn

滾動：scroll

標籤頁：tab

文章列表：list

提示資訊：msg

當前的: current

小技巧：tips

圖示: icon

註釋：note

指南：guide

服務：service

熱點：hot

新聞：news

下載：download

投票：vote

合作伙伴：partner

友情連結：link

版權：copyright

(四)class的命名:

(1)顏色:使用顏色的名稱或者16進位制程式碼,如

.red { color: red; }

.f60 { color: #f60; }

.ff8600 { color: #ff8600; }

（2）字型大小,直接使用”font+字型大小”作為名稱,如

.font12px { font-size: 12px; }

.font9pt {font-size: 9pt; }

(3)對齊樣式,使用對齊目標的英文名稱,如

.left { float:left; }

.bottom { float:bottom; }

(4)標題欄樣式,使用”類別+功能”的方式命名,如

.barnews { }

.barproduct { }