JavaScript 編碼風格指南

小賢筆記發表於2018-07-24

本文是從簡書複製的, 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了

相關文章