本文是從簡書複製的, markdown語法可能有些出入, 想看"正版"和更多內容請關註 簡書: "小賢筆記" 寫作本文旨在加深自己印象,也為了更多人的瞭解到JS編碼風格,提高自己的編碼質量 想瞭解更多的內容請閱讀《編寫可維護的JavaScript》 縮進 + 每一行的層級由4個空格組成,避免使用製表 ...
本文是從簡書複製的, markdown語法可能有些出入, 想看"正版"和更多內容請關註 簡書: 小賢筆記
寫作本文旨在加深自己印象,也為了更多人的瞭解到JS編碼風格,提高自己的編碼質量
想瞭解更多的內容請閱讀《編寫可維護的JavaScript》
縮進
- 每一行的層級由4個空格組成,避免使用製表符 (Tab) 進行縮進
// 好的寫法
if (true) {
doSomething();
}
行的長度
- 每行長度不應超過80個字元。如果一行超過80個字元,應當在一個運算符 (逗號, 加號等) 後換行。下一行應當增加兩級縮進(8個字元)
// 好的寫法
doSomething(argument1, argument2, aegument3, argument4,
argument5);
// 不好的寫法:第二行只有4個空格的縮進
doSomething(argument1, argument2, aegument3, argument4,
argument5);
// 不好的寫法:在運算符之前換行
doSomething(argument1, argument2, aegument3, argument4
, argument5);
原始值
- 字元串應當始終使用雙引號 (避免使用單引號) 且保持一行,避免在字元串中使用斜線另起一行
個人建議: html 用雙引號, js 用單引號; 反之, 亦可
// 好的寫法
var name = "Nicholas";
// 不好的寫法: 單引號
var name = 'Nicholas';
// 不好的寫法: 字元串結束之前換行
var longString = "Here's the story, of a man \
named Brady.";
- 數字應當使用十進位整數,科學計演算法表示整數,十六進位整數,或者十進位浮點小數,小數前後應當至少保留一位數字。避免使用八進位直接量
// 好的寫法
var count = 10;
// 好的寫法
var price = 10.0;
var price = 10.00;
// 好的寫法
var num = 0xA2;
// 好的寫法
var num = 1e23;
// 不好的寫法: 十進位數字以小數點結尾
var price = 10.;
// 不好的寫法: 十進位數字以小數點開頭
var price = .1;
// 不好的寫法: 八進位 (base 8) 寫法已廢棄
var num = 010;
- 特殊值null除了下述情況下應當避免使用
- 用來初始化一個變數,這個變數可能被賦值為一個對象
- 用來和一個已經初始化的變數比較,這個變數可以是也可以不是一個對象
- 當函數的參數期望是對象時,被用作參數傳入
- 當函數的返回值期望是對象時,被用作返回值傳出
```
// 好的寫法
var person = null;
// 好的寫法
function getPerson() {
if (condition) {
return new Person("Nicholas");
} else {
return null;
}
}
// 好的寫法
var person = getPerson();
if (person != null) {
doSomething();
}
// 不好的寫法: 和一個未被初始化的變數比較
var person;
if (person != null) {
doSomething();
}
// 不好的寫法: 通過測試判斷某個參數是否傳遞
function doSomething(arg1, arg2, arg3, arg4) {
if (arg4 != null) {
doSomethingElse();
}
}
+ 避免使用特殊值 undefined。判斷一個變數是否定義應當使用 typeof 操作符
// 好的寫法
if (typeof variable == "undefined") {
// do something
}
// 不好的寫法: 使用了 undefined 直接量
if (variable == undefined) {
// do something
}
## 運算符間距
+ 二元運算符前後必須使用一個空格來保持表達式的整潔。操作符包括賦值運算符和邏輯運算符
// 好的寫法
var found = (values[i] === item);
// 好的寫法
if (found && (count > 10)) {
doSomething();
}
// 好的寫法
for (i = 0; i < count; i++) {
process(i);
}
// 不好的寫法: 丟失了空格
var found = (values[i]===item);
// 不好的寫法: 丟失了空格
if (found&&(count>10)) {
doSomething();
}
// 不好的寫法: 丟失了空格
for (i=0; i<count; i++) {
process(i);
}
## 括弧間距
+ 當使用括弧時,緊接左括弧之後和緊接右括弧之前不應該有空格
// 好的寫法
var found = (values[i] === item);
// 好的寫法
if (found && (count > 10)) {
doSomething();
}
// 好的寫法
for (i = 0; i < count; i++) {
process(i);
}
// 不好的寫法: 左括弧之後有額外的空格
var found = ( values[i] === item);
// 不好的寫法: 右括弧之前有額外的空格
if (found && (count > 10) ) {
doSomething();
}
// 不好的寫法: 參數兩邊有額外的空格
for (i = 0; i < count; i++) {
process( i );
}
## 對象直接量
+ 對象直接量應當有如下格式
+ 起始左花括弧應當同表達式保持同一行
+ 每個屬性的名值對應當保持一個縮進,第一個屬性應當在左花括弧後另起一行
+ 每個屬性的名值對應當使用不含引號的屬性名,其後緊跟一個冒號(之前不含空格),而後是值
+ 倘若屬性值是函數類型,函數體應當在屬性名之下另起一行,而且其前後均應保留一個空行
+ 一組相關的屬性前後可以插入空行以提升代碼的可讀性
+ 結束的右花括弧應當獨占一行
// 好的寫法
var object = {
key1: value1,
key2: value2,
func: function() {
// doSomething
},
key3: value3
};
// 不好的寫法:不恰當的縮進
var object = {
key1: value1,
key2: value2
};
// 不好的寫法:函數體周圍缺少空行
var object = {
key1: value1,
key2: value2,
func: function() {
// doSomething
},
key3: value3
};
+ 當對象字面量作為函數參數時,如果值是變數,起始花括弧應當同函數名在同一行。所有其餘先前列出的規則同樣適用
// 好的寫法
doSomething({
key1: value1,
key2: value2
});
// 不好的寫法:所有代碼在一行上
doSomething({ key1: value1, key2: value2 });
## 註釋
+ 頻繁地使用註釋有助於他人理解你的代碼。如下情況應當使用註釋
+ 代碼晦澀難懂
+ 可能被誤認為錯誤的代碼
+ 必要但不明顯的針對特定瀏覽器的代碼
+ 對於對象、方法或者屬性,生成文檔是有必要的(使用恰當的文檔註釋)
#### 單行註釋
+ 單行註釋應當用來說明一行代碼或者一組相關的代碼。單行註釋可能有三種使用方式
+ 獨占一行的註釋,用來解釋下一行代碼
+ 在代碼行的尾部的註釋,用來解釋它之前的代碼
+ 多行,用來註釋掉一個代碼塊
// 好的寫法
if (condition) {
// 如果代碼執行到這裡,則表明通過了所有安全性檢查
allowed();
}
// 不好的寫法:註釋之前沒有空行
if (condition) {
// 如果代碼執行到這裡,則表明通過了所有安全性檢查
allowed();
}
// 不好的寫法:錯誤的縮進
if (condition) {
// 如果代碼執行到這裡,則表明通過了所有安全性檢查
allowed();
}
// 不好的寫法:這裡應當使用多行註釋
// 接下來的這段代碼非常難,那麼,讓我詳細的解釋一下
// 這段代碼的作用氏首先判斷條件是否為真
// 只有為真時才會執行。這裡的條件是通過
// 多個函數計算出來的,在整個會話生命周期內
// 這個值氏可以被修改的
if (condition) {
// 如果代碼執行到這裡,則表明通過了所有安全檢查
allowed();
}
+ 對於代碼行尾單行註釋的情況,應確保代碼結尾同註釋之間至少一個縮進
// 好的寫法
var result = something + somethingElse; // somethingElse will never be null
// 不好的寫法: 代碼和註釋間沒有足夠的空格
var result = something + somethingElse;// somethingElse will never be null
+ 註釋一個代碼塊時在連續多行使用單行註釋是唯一可以接受的情況.。多行註釋不應當在這種情況下使用
// 好的寫法
// if (condition) {
// doSomething();
// }
#### 多行註釋
+ 多行註釋應當在代碼需要更多文字去解釋的時候使用。每個多行註釋都至少有如下三行
+ 首行僅僅包括`/*`註釋開始。該行不應當有其他文字
+ 接下來的行以`*`開頭並保持左對齊。這些可以有文字描述
+ 最後一行以`*/`開頭並同先前行保持對齊。也不應有其他文字
+ 多行註釋的首行應當保持同它描述代碼的相同層次的縮進。後續的每行應當有同樣層次的縮進並附加一個空格(為了適當保持`*`字元的對齊)。每一個多行代碼之前應當預留一個空行
// 好的寫法
if (condition) {
/*
* 如果代碼執行到這裡
* 說明通過了所有的安全檢測
*/
allowed();
}
// 不好的寫法: 註釋之前無空行
if (condition) {
/
如果代碼執行到這裡
* 說明通過了所有的安全檢測
*/
allowed();
}
// 不好的寫法: 星號後沒有空格
if (condition) {
/*
*如果代碼執行到這裡
*說明通過了所有的安全檢測
*/
allowed();
}
// 不好的寫法: 錯誤的縮進
if (condition) {
/*
- 如果代碼執行到這裡
- 說明通過了所有的安全性檢測
*/
allowed();
}
// 不好的寫法: 代碼尾部註釋不要用多行註釋格式
var result = something + somethingElse; /somethingElse 不應當取值為null/
## 聲明
#### 註釋聲明
+ 註釋有時候也可以用來給一段代碼聲明額外的信息。這些聲明的格式以單個單詞打頭並緊跟一個冒號。可以使用的聲明如下
+ TODO
+ 說明代碼還未完成。應當包含下一步要做的事情
+ HACK
+ 表明代碼實現走了一個捷徑。應當包含為何使用 hack 的原因。這也可能表明該問題可能會有更好的解決辦法
+ XXX
+ 說明代碼是有問題的並應當儘快修複
+ FIXME
+ 說明代碼是有問題的並應儘快修複。重要性略次於XXX
+ REVIEW
+ 說明代碼在任何可能的改動都需要評審
+ 這些聲明可能在一行或者多行註釋中使用,並且應當遵循同一般註釋類型相同的格式規則
// 好的寫法
// TODO: 我希望找到一種更快的方式
doSomething();
// 好的寫法
/*
- HACK: 不得不針對 IE 做的特殊處理. 我計劃後續有時間時
- 重寫這部分. 這些代買可能需要在 v1.2 版本之前替換掉
*/
if (document.all) {
doSomething();
}
// 好的寫法
// REVIEW: 有更好的方法嗎?
if (document.all) {
doSomething();
}
// 不好的寫法: 註釋聲明空格不正確
// TODO : 我希望找到一種更快的方式
doSomething();
// 不好的寫法: 代碼和註釋應當保持同樣的縮進
// REVIEW: 有更好的方法嗎?
if (document.all) {
doSomething();
}
#### 變數聲明
+ 所有的變數在使用前都應當事先定義。變數定義應當放在函數開頭,使用一個 var 表達式每行一個變數。除了首行,所有行都應當多一層縮進以使變數名能夠垂直方向對齊。變數定義時應當初始化,並且賦值操作符應當爆出一致的縮進。初始化的變數應當在未初始化變數之前
// 好的寫法
var count = 10,
name = "Nicholas",
found = false,
empty;
// 不好的寫法: 不恰當的初始化賦值
var count = 10,
name = "Nicholas",
found= false,
empty;
// 不好的寫法: 錯誤的縮進
var count = 10,
name = "Nicholas",
found = false,
empty;
// 不好的寫法: 多個定義寫在一行
var count = 10, name = "Nicholas",
found = false, empty;
// 不好的寫法: 未初始化的變數放在最前面
var empty,
count = 10,
name = "Nicholas",
found = false;
// 不好的寫法: 多個 var 表達式
var count = 10,
name = "Nicholas";
var found = false,
empty;
#### 函數聲明
+ 函數應當在使用前提前定義。一個不是作為方法的函數(也就是說沒有作為一個對象的屬性)應當使用函數定義的格式(不是函數表達式和 Function 構造器格式)。函數名和開始圓括弧之間不應當有空格。結束的圓括弧和右邊的花括弧之間應該留一個空格。右側的花括弧應當同 function 關鍵字保持同一行。開始和結束括弧之間不應該有空格。參數名之間應當在都好之後保留一個空格。函數體應當保持一級縮進。
// 好的寫法
function doSomething(arg1, arg2) {
return arg1 + arg2;
}
// 不好的寫法: 第一行不恰當的空格
function doSomething (arg1, arg2) {
return arg1 + arg2;
}
// 不好的寫法: 函數表達式
var doSomething = function doSomething(arg1, arg2) {
return arg1 + arg2;
}
// 不好的寫法: 左側的花括弧位置不對
function doSomething(arg1, arg2)
{
return arg1 + arg2;
}
// 錯誤的寫法: 使用了 Function 構造器
var doSomething = new Function("arg1", "arg2", "return arg1 + arg2")
+ 其他函數內部定義的函數應當在 var 語句後立即定義
// 好的寫法
function outer() {
var count = 10,
name = "Nicholas",
found = false,
empty;
function inner() {
// 代碼
}
// 調用 inner() 的代碼
}
// 不好的寫法: inner 函數的定義先於變數
function outer() {
function inner() {
// 代碼
}
var count = 10,
name = "Nicholas",
found = false,
empty;
// 調用 inner() 的代碼
}
+ 匿名函數可能作為方法賦值給對象,或者作為其他函數的參數。function 關鍵字同開始括弧之間不應有空格
// 好的寫法
object.method = function() {
// 代碼
};
// 不好的寫法: 不正確的空格
object.method = function () {
// 代碼
};
+ 立即被調用的函數應當在行數調用的外層用圓括弧包裹
// 好的寫法
var value = (function() {
// 函數體
return {
message: "Hi"
}
}());
// 不好的寫法: 函數調用外層沒有用圓括弧包裹
var value = function() {
// 函數體
return {
message: "Hi"
}
}();
// 不好的寫法: 圓括弧位置不當
var value = (function() {
// 函數體
return {
message: "Hi"
}
})();
#### 賦值
+ 給變數賦值時,如果右側是含有比較語句的表達式,需要用圓括弧包裹
// 好的寫法
var flag = (i < count);
// 不好的寫法:遺漏圓括弧
var flag = i < count;
## 命名
+ 變數和函數在命名時應當小心。命名應僅限於數字字母字元,某些情況下可以使用下劃線。最好不要在任何命名中使用美元符號($)或者反斜杠(\\)
+ 變數命名應當採用駝峰命名格式,首字母小寫,每個單詞首字母大寫。變數名的第一個單詞應當是一個名詞 (而非動詞) 以避免同函數混淆。不要在變數名中使用下劃線
// 好的寫法
var accountNumber = "2312";
// 不好的寫法:大寫字母開頭
var AccountNumber = "2312";
// 不好的寫法:動詞開頭
var getAccountNumber = "2312";
// 不好的寫法:使用下劃線
var account_number = "2312";
+ 函數名也應當採用駝峰命名格式。函數名的第一個單詞應當是動詞(而非名詞)來避免同變數混淆。函數名中最好不要使用下劃線
// 好的寫法
function doSomething() {
// 代碼
}
// 不好的寫法:大寫字母開頭
function DoSomething() {
// 代碼
}
// 不好的寫法:名詞開頭
function something() {
// 代碼
}
// 不好的寫法:使用下劃線
function do_something() {
// 代碼
}
+ 這裡有一些使用動詞常見的約定
|動詞|含義|
|:---:|:---:|
|can|函數返回一個布爾值|
|has|函數返回一個布爾值|
|is|函數返回一個布爾值|
|get|函數返回一個非布爾值|
|set|函數用來保存一個值|
if (isEnabled()) {
setName("Nicholas");
}
if (getName() === "Nicholas") {
doSomething();
}
+ 構造函數——通過new運算符創建新對象的函數——也應當以駝峰格式命名並且首字元大寫。構造函數名稱應當以非動詞開頭,因為new代表著創建一個對象實例的操作
// 好的寫法
function MyObject() {
// 代碼
}
// 不好的寫法:小寫字母開頭
function myObject() {
// 代碼
}
// 不好的寫法:使用下劃線
function my_object() {
// 代碼
}
// 不好的寫法:動詞開頭
function getMyObject() {
// 代碼
}
+ 常量(值不會被改變的變數)的命名應當是所有大寫字母,不同單詞之間單個下劃線隔開
// 好的寫法
var TOTAL_COUNT = 10;
// 不好的寫法:駝峰形式
var totalCount = 10;
// 不好的寫法:混合形式
var total_COUNT = 10;
+ 對象的屬性同變數的命名規則相同。對象的方法同函數的命名規則相同。如果屬性或者方法是私有的,應當在之前加上一個下劃線
// 好的寫法
var object = {
_count: 10,
_getCount: function() {
return this._count;
}
}
## 嚴格模式
+ 嚴格模式應當僅限在函數內部使用,千萬不要在全局使用
// 不好的寫法:全局使用嚴格模式
"use strict";
function doSomething() {
// 代碼
}
// 好的寫法
function doSomething() {
"use strict";
// 代碼
}
+ 如果你期望在多個函數中使用嚴格模式而不需要多次聲明“use strict”,可以使用立即被調用的函數
// 好的寫法
(function() {
"use strict";
function doSomething() {
// 代碼
}
function doSomethingElse() {
// 代碼
}
}());
## 運算符
#### 等號運算符
+ 使用===(嚴格相等)和!==(嚴格不相等)代替==(相等)和!=(不等)來避免弱類型轉換錯誤
// 好的寫法
var same = (a === b);
// 好的寫法
var same = (a == b);
#### 三元運算符
+ 三元運算符應當僅僅用在條件賦值語句中,而不要作為if語句的替代品
// 好的寫法
var value = condition ? value1 : value2;
// 不好的寫法: 沒有賦值, 應當使用 if 表達式
condition ? doSomething() : doSomethingElse;
## 語句
#### 簡單語句
+ 每一行最多只包含一條語句。所有簡單的語句都應該以分號(;)結束
// 好的寫法
count++;
a = b;
// 不好的寫法:多個表達式寫在一行
count++; a = b;
+ 返回語句
+ 返回語句當返回一個值的時候不應當使用圓括弧包裹,除非在某些情況下這麼做可以讓返回值更容易理解。例如
return;
return collection.size();
return (size > 0 ? size : defaultSize);
#### 複合語句
+ 複合語句是大括弧括起來的語句列表
+ 括起來的語句應當較複合語句多縮進一個層級
+ 開始的大括弧應當在複合語句所在行的末尾;結束的大括弧應當獨占一行且同複合語句的開始保持同樣的縮進
+ 當語句是控制結構的一部分時,諸如 if 或者 for 語句,所有語句都需要用大括弧括起來,也包括單個語句。這個約定使得我們更方便地添加語句而不用擔心忘記加括弧而引起 bug
+ 像 if 一樣的語句開始的關鍵詞,其後應該緊跟一個空格,起始大括弧應當在空格之後
#### if 語句
+ if 語句應當是下麵的格式
if (condition) {
statements
}
if (condition) {
statements
} else {
statements
}
if (condition) {
statements
} else if (condition) {
statements
} else {
statements
}
+ 絕不允許在if語句中省略花括弧
// 好的寫法
if (condition) {
doSomething();
}
// 不好的寫法:不恰當的空格
if (condition){
doSomething();
}
// 不好的寫法: 遺漏花括弧
if (condition)
doSomething();
// 不好的寫法:所有代碼都在一行
if (condition) { doSomething(); }
// 不好的寫法:所有代碼都在一行且沒有花括弧
if (condition) doSomething();
#### for 語句
+ for 類型的語句應當是下麵的格式
for (initialization; condition; update) {
statements
}
for (variable in object) {
statements
}
+ for語句的初始化部分不應當有變數聲明
// 好的方法
var i,
len;
for (i=0, len=0; i < len; i++) {
// 代碼
}
// 不好的寫法:初始化時候聲明變數
for (var i=0, len=0; i < len; i++) {
// 代碼
}
// 不好的寫法:初始化時候聲明變數
for (var prop in object) {
// 代碼
}
+ 當使用for-in語句時,記得使用hasOwnProperty()進行雙重檢查來過濾對象的成員
#### while 語句
+ while 類的語句應當是下麵的格式
while (condition) {
statements
}
#### do 語句
+ do 類的語句應當是下麵的格式
do {
statements
} while (condition);
#### switch 語句
+ switch 類的語句應當是如下格式
switch (expression) {
case expression:
statements
default:
statements
}
+ switch 下的第一個 case 都應當保持一個縮進。除第一個之外包括 default 在內的每一個 case 都應當在之前保持一個空行
+ 每一組語句(除了default)都應當以 break、return、throw 結尾,或者用一行註釋表示跳過
// 好的寫法
switch (value) {
case 1:
/* falls through */
case 2:
doSomething();
break;
case 3:
return true;
default:
throw new Error("Some error");
}
+ 如果一個switch語句不包含default情況,應當用一行註釋代替
// 好的寫法
switch (value) {
case 1:
/* falls through */
case 2:
doSomething();
break;
case 3:
return true;
default:
// 沒有default
}
#### try 語句
+ try類的語句應當格式如下
try {
statements
} catch (variable) {
statements
}
try {
statements
} catch (variable) {
statements
} finally {
statements
}
```
留白
- 在邏輯相關的代碼之間添加空行代碼可以提高代碼的可讀性
- 兩行空行僅限於在如下情況下使用
- 在不同的源代碼文件之間
- 在類和介面定義之間
- 單行空行僅限在如下情況中使用
- 方法之間
- 方法中局部變數和第一行語句之間
- 多行或者單行註釋之前
- 方法中邏輯代碼塊之間以提升代碼的可讀性
- 空格應當在如下的情況下使用
- 關鍵詞後跟括弧的情況應當用空格隔開
- 參數列表中逗號之後應當保留一個空格
- 所有的除了點(.)之外的二元運算符,其操作數都應當用空格隔開。單目運算符的操作數之間不應該用空白隔開,例如一元減號,遞增(++),遞減(--)
- for 語句的表達式之間應當用空格隔開
註意
- 切勿使用像 String 一類的原始包裝類型創建新的對象
- 避免使用 eval()
- 避免使用with語句。該語句在嚴格模式中不復存在,可能在未來的ECMAScript 標準中也將去除
最後
- 上述指南並不是在開發過程中必須完全遵守的 (比如說引號和縮進等),我們可以只汲取其中的一部分來改善自己的編碼風格,讓自己的代碼易讀、可維護。關於編碼風格,每個團隊都有自己的特色,只要保持團隊一致性,可以高效的開發就OK了