最佳原則
堅(jiān)持制定好的代碼規(guī)范泰讽。
無(wú)論團(tuán)隊(duì)人數(shù)多少手蝎，代碼應(yīng)該同出一門(mén)显熏。
以下為精簡(jiǎn)且必須堅(jiān)持的代碼規(guī)范雄嚣。精簡(jiǎn)版從綜合目前小鯨的代碼習(xí)慣在騰訊團(tuán)隊(duì)的規(guī)范文檔中進(jìn)行了提取和修改。更多詳細(xì)內(nèi)容請(qǐng)參看
Code Guide by @AlloyTeam喘蟆。
命名規(guī)范
文件命名
全部采用駝峰方式。
例：myProjectName.js myProjectName.css
git分支命名
新需求開(kāi)發(fā)以 feature/{關(guān)鍵詞}_{擬發(fā)布日期}開(kāi)頭
bug修復(fù)以 hotfix/{關(guān)鍵詞}_{擬發(fā)布日期}開(kāi)頭
關(guān)鍵詞全部為小寫(xiě)鼓鲁，以下劃線(xiàn)分割
日期格式為20200306
例：feature/update_coupons_20200306 hotfix/image_change_type_20200306
HTML
語(yǔ)法
- 縮進(jìn)使用soft tab（4個(gè)空格）蕴轨；
- 在屬性上，使用雙引號(hào)骇吭，不要使用單引號(hào)橙弱；
- 不要在自動(dòng)閉合標(biāo)簽結(jié)尾處使用斜線(xiàn)（HTML5 規(guī)范 指出他們是可選的）；
<!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>
lang屬性
根據(jù)HTML5規(guī)范：
應(yīng)在html標(biāo)簽上加上lang屬性燥狰。這會(huì)給語(yǔ)音工具和翻譯工具幫助棘脐，告訴它們應(yīng)當(dāng)怎么去發(fā)音和翻譯。
但sitepoint只是給出了語(yǔ)言的大類(lèi)龙致，例如中文只給出了zh蛀缝，但是沒(méi)有區(qū)分香港，臺(tái)灣目代，大陸屈梁。而微軟給出了一份更加詳細(xì)的語(yǔ)言列表，其中細(xì)分了zh-cn, zh-hk, zh-tw榛了。
<!DOCTYPE html>
<html lang="en-us">
...
</html>
字符編碼
通過(guò)聲明一個(gè)明確的字符編碼在讶，讓瀏覽器輕松、快速的確定適合網(wǎng)頁(yè)內(nèi)容的渲染方式霜大，通常指定為'UTF-8'构哺。
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
</head>
...
</html>
IE兼容模式
用 <meta> 標(biāo)簽可以指定頁(yè)面應(yīng)該用什么版本的IE來(lái)渲染；
如果你想要了解更多战坤，請(qǐng)點(diǎn)擊這里曙强；
不同doctype在不同瀏覽器下會(huì)觸發(fā)不同的渲染模式（這篇文章總結(jié)的很到位）。
css&scss
主要注意命名湖笨，其他格式問(wèn)題旗扑，按照編輯器格式化，就可以慈省。
縮進(jìn)
使用soft tab（4個(gè)空格）臀防。
命名
- 類(lèi)名使用小寫(xiě)字母眠菇，以中劃線(xiàn)分隔
- id采用駝峰式命名
- scss中的變量、函數(shù)袱衷、混合捎废、placeholder采用駝峰式命名
/* class */
.element-content {
...
}
/* id */
#myDialog {
...
}
/* 變量 */
$colorBlack: #000;
/* 函數(shù) */
@function pxToRem($px) {
...
}
/* 混合 */
@mixin centerBlock {
...
}
/* placeholder */
%myDialog {
...
}
顏色
顏色16進(jìn)制用小寫(xiě)字母；
顏色16進(jìn)制盡量用簡(jiǎn)寫(xiě)致燥。
/* not good */
.element {
color: #ABCDEF;
background-color: #001122;
}
/* good */
.element {
color: #abcdef;
background-color: #012;
}
雜項(xiàng)
- 不允許有空的規(guī)則登疗；
/* not good */
.element {
}
- 元素選擇器用小寫(xiě)字母；
/* not good */
LI {
...
}
- 去掉小數(shù)點(diǎn)前面的0嫌蚤；
/* not good */
.element {
color: rgba(0, 0, 0, 0.5);
}
/* good */
.element {
color: rgba(0, 0, 0, .5);
}
- 屬性值'0'后面不要加單位辐益；
/* not good */
.element {
width: 0px;
}
/* good */
.element {
width: 0;
}
- 不要在同個(gè)規(guī)則里出現(xiàn)重復(fù)的屬性，如果重復(fù)的屬性是連續(xù)的則沒(méi)關(guān)系脱吱；
/* not good */
.element {
color: rgb(0, 0, 0);
width: 50px;
color: rgba(0, 0, 0, .5);
}
/* good */
.element {
color: rgb(0, 0, 0);
color: rgba(0, 0, 0, .5);
}
不要在一個(gè)文件里出現(xiàn)兩個(gè)相同的規(guī)則智政；
用 border: 0; 代替 border: none;；
選擇器不要超過(guò)4層（在scss中如果超過(guò)4層應(yīng)該考慮用嵌套的方式來(lái)寫(xiě)）箱蝠；
發(fā)布的代碼中不要有 @import续捂；
盡量少用'*'選擇器。
JavaScript
變量命名
- 標(biāo)準(zhǔn)變量采用駝峰式命名（除了對(duì)象的屬性外宦搬，主要是考慮到cgi返回的數(shù)據(jù)）
- 'ID'在變量名中全大寫(xiě)
- 'URL'在變量名中全大寫(xiě)
- 'Android'在變量名中大寫(xiě)第一個(gè)字母
- 'iOS'在變量名中小寫(xiě)第一個(gè)牙瓢，大寫(xiě)后兩個(gè)字母
- 常量全大寫(xiě)，用下劃線(xiàn)連接
- 構(gòu)造函數(shù)间校，大寫(xiě)第一個(gè)字母
- jquery對(duì)象必須以'$'開(kāi)頭命名
var thisIsMyName;
var goodID;
var reportURL;
var AndroidVersion;
var iOSVersion;
var MAX_COUNT = 10;
function Person(name) {
this.name = name;
}
// not good
var body = $('body');
// good
var $body = $('body');
變量聲明
一個(gè)函數(shù)作用域中所有的變量聲明盡量提到函數(shù)首部矾克，用一個(gè)var聲明，不允許出現(xiàn)兩個(gè)連續(xù)的var聲明撇簿。
function doSomethingWithItems(items) {
// use one var
var value = 10,
result = value + 10,
i,
len;
for (i = 0, len = items.length; i < len; i++) {
result += 10;
}
}
縮進(jìn)
使用soft tab（4個(gè)空格）聂渊。
分號(hào)
以下幾種情況后需加分號(hào)：
- 變量聲明
- 表達(dá)式
- return
- throw
- break
- continue
- do-while
/* var declaration */
var x = 1;
/* expression statement */
x++;
/* do-while */
do {
x++;
} while (x < 10);
空格
書(shū)寫(xiě)時(shí)多注意，盡量保持代碼的美觀(guān)整潔四瘫，不做過(guò)分要求汉嗽。
空行
以下幾種情況需要空行：
- 變量聲明后（當(dāng)變量聲明在代碼塊的最后一行時(shí)，則無(wú)需空行）
- 注釋前（當(dāng)注釋在代碼塊的第一行時(shí)找蜜，則無(wú)需空行）
- 代碼塊后（在函數(shù)調(diào)用饼暑、數(shù)組、對(duì)象中則無(wú)需空行）
- 文件最后保留一個(gè)空行
// need blank line after variable declaration
var x = 1;
// not need blank line when variable declaration is last expression in the current block
if (x >= 1) {
var y = x + 1;
}
var a = 2;
// need blank line before line comment
a++;
function b() {
// not need blank line when comment is first line of block
return a;
}
// need blank line after blocks
for (var i = 0; i < 2; i++) {
if (true) {
return false;
}
continue;
}
var obj = {
foo: function() {
return 1;
},
bar: function() {
return 2;
}
};
換行
換行的地方洗做，行末必須有','或者運(yùn)算符弓叛；
// not good
var a = {
b: 1
, c: 2
};
x = y
? 1 : 2;
// good
var a = {
b: 1,
c: 2
};
x = y ? 1 : 2;
x = y ?
1 : 2;
以下幾種情況不需要換行：
- 下列關(guān)鍵字后：
else, catch, finally - 代碼塊'{'前
// no need line break with 'else', 'catch', 'finally'
if (condition) {
...
} else {
...
}
try {
...
} catch (e) {
...
} finally {
...
}
以下幾種情況需要換行：
- 代碼塊'{'后和'}'前
- 變量賦值后
數(shù)組、對(duì)象
對(duì)象屬性名不需要加引號(hào)诚纸；
對(duì)象以縮進(jìn)的形式書(shū)寫(xiě)撰筷，不要寫(xiě)在一行；
數(shù)組畦徘、對(duì)象最后不要有逗號(hào)毕籽。
// not good
var a = {
'b': 1
};
var a = {b: 1};
var a = {
b: 1,
c: 2,
};
// good
var a = {
b: 1,
c: 2
};
單行注釋?zhuān)?=重點(diǎn)==）
雙斜線(xiàn)后抬闯，必須跟一個(gè)空格；
縮進(jìn)與下一行代碼保持一致关筒；
可位于一個(gè)代碼行的末尾溶握，與代碼間隔一個(gè)空格。
if (condition) {
// if you made it here, then all security checks passed
allowed();
}
var zhangsan = 'zhangsan'; // one space after code
多行注釋?zhuān)?=重點(diǎn)==）
最少三行, '*'后跟一個(gè)空格蒸播，具體參照右邊的寫(xiě)法睡榆；
建議在以下情況下使用：
- 難于理解的代碼段
- 可能存在錯(cuò)誤的代碼段
- 瀏覽器特殊的HACK代碼
- 業(yè)務(wù)邏輯強(qiáng)相關(guān)的代碼
文檔注釋?zhuān)?=重點(diǎn)==）
各類(lèi)標(biāo)簽@param, @method等請(qǐng)參考usejsdoc和JSDoc Guide；
建議在以下情況下使用：
- 所有常量
- 所有函數(shù)
- 所有類(lèi)
/**
* @desc 一個(gè)帶參數(shù)的函數(shù)
* @builder lixuepeng
* @update lixuepeng [20200306]
* @param {string} a - 參數(shù)a
* @param {number} b=1 - 參數(shù)b默認(rèn)值為1
* @param {string} c=1 - 參數(shù)c有兩種支持的取值</br>1—表示x</br>2—表示xx
* @param {object} d - 參數(shù)d為一個(gè)對(duì)象
* @param {string} d.e - 參數(shù)d的e屬性
* @param {string} d.f - 參數(shù)d的f屬性
* @param {object[]} g - 參數(shù)g為一個(gè)對(duì)象數(shù)組
* @param {string} g.h - 參數(shù)g數(shù)組中一項(xiàng)的h屬性
* @param {string} g.i - 參數(shù)g數(shù)組中一項(xiàng)的i屬性
* @param {string} [j] - 參數(shù)j是一個(gè)可選參數(shù)
*/
function foo(a, b, c, d, g, j) {
...
}
引號(hào)
最外層統(tǒng)一使用單引號(hào)袍榆。
// not good
var x = "test";
// good
var y = 'foo',
z = '<div id="test"></div>';
括號(hào)
下列關(guān)鍵字后必須有大括號(hào)（即使代碼塊的內(nèi)容只有一行）：if, else, for, while, do, switch, try, catch, finally, with胀屿。
// not good
if (condition)
doSomething();
// good
if (condition) {
doSomething();
}
jshint
- 用'===', '!=='代替'==', '!='；
- for-in里一定要有hasOwnProperty的判斷蜡塌；
// good
for (key in obj) {
if (obj.hasOwnProperty(key)) {
// be sure that obj[key] belongs to the object and was not inherited
console.log(obj[key]);
}
}
- 不要在內(nèi)置對(duì)象的原型上添加方法碉纳，如Array, Date；
// not good
Array.prototype.count = function(value) {
return 4;
};
- 不要在內(nèi)層作用域的代碼里聲明了變量馏艾，之后卻訪(fǎng)問(wèn)到了外層作用域的同名變量；
// not good
var x = 1;
function test() {
if (true) {
var x = 0;
}
x += 1;
}
- 不要在一句代碼中單單使用構(gòu)造函數(shù)奴愉，記得將其賦值給某個(gè)變量琅摩；
// not good
new Person();
// good
var person = new Person();
- 不要在一些不需要的地方加括號(hào)，例：
delete(a.b)锭硼； - 不要聲明了變量卻不使用房资；
- 不要在應(yīng)該做比較的地方做賦值；
// not good
if (a = 10) {
a++;
}
- debugger不要出現(xiàn)在提交的代碼里;
- 數(shù)組中不要存在空元素檀头；
- 不要在循環(huán)內(nèi)部聲明函數(shù)轰异；
// not good
var nums = [];
for (var i = 0; i < 10; i++) {
(function(i) {
nums[i] = function(j) {
return i + j;
};
}(i));
}
- 不要像這樣使用構(gòu)造函數(shù)，例：
new function () { ... }, new Object暑始；
