> 原作： [https://github.com/ryanmcdermott/clean-code-javascript](https://github.com/ryanmcdermott/clean-code-javascript)<br>

> 原作者： [https://github.com/ryanmcdermott](https://github.com/ryanmcdermott) <br>

> 譯者： [https://github.com/trylovetom](https://github.com/trylovetom)

## 目錄（Table of Contents）

1. [介紹（Introduction）](#介紹Introduction)

2. [變數（Variables）](#變數Variables)

3. [函數（Functions）](#函數Functions)

4. [物件（Objects）與資料結構（Data Structures）](#物件Objects與資料結構Data-Structures)

5. [類別（Classes）](#類別Classes)

6. [物件導向基本原則（SOLID）](#物件導向基本原則SOLID)

7. [測試（Testing）](#測試Testing)

8. [並發（Concurrency）](#並發Concurrency)

9. [錯誤處理（Error Handling）](#錯誤處理Error-Handling)

10. [格式化（Formatting）](#格式化Formatting)

11. [註解（Comments）](#註解Comments)

12. [翻譯（Translation）](#翻譯Translation)

## 介紹（Introduction）

<br>透過計算閱讀程式碼時的咒罵次數，來評估軟體品質<br><br>

文章作者根據 Robert C. Martin 的[《無暇的程式碼》](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)，撰寫一份適用於 JavaScript 的原則。本文不是風格指南（Style Guide），而是教導你撰寫出[可閱讀、可重複使用與可重構](https://github.com/ryanmcdermott/3rs-of-software-architecture)的 JS 程式碼。

注意！你不必嚴格遵守每一項原則，有些甚至不被大眾所認同。雖然這只是份指南，卻是來自《無暇的程式碼》作者的多年結晶。

軟體工程只發展了五十年，仍然有很多地方值得去探討。當軟體與建築一樣古老時，也許會有一些墨守成規的原則。但現在，先讓這份指南當試金石，作為你和團隊的 JS 程式碼標準。

還有一件事情：知道這些原則，並不會立刻讓你成為出色的開發者，長期奉行它們，不代表你能高枕無憂不再犯錯。但是，千里之行，始於足下，時常與志同道合們進行討論（Code Review），改善不完備之處。不要因為自己寫出來的程式碼很糟糕而害怕分享，而是要畏懼自己居然寫出了這樣的程式碼！

**譯者序**

> 獻給[傲嬌文創](https://alljoint.tw/)的所有工程師夥伴，與熱愛 JavaScript 的各位。

《無暇的程式碼》是一本好書，是不可否認這個事實。我熱愛著 JS，當找到這份 JS 版本的後，我無比開心立刻著手翻譯，因此有了這份《無暇的程式碼 JavaScript》。對於 *Clean Code* 的書名採用博碩文化的翻譯，也是對原版譯者的尊敬。本翻譯中會穿插一些我對文章中註解，也請讀者原諒我的叨擾。另外專業術語的翻譯有可能會有出入，我會標示出英文原文，避免讀者誤解。如有翻譯或是理解上的錯誤，煩請聯絡我，謝謝。（聯絡方式在上方，我的 GitHub 中。）

## 變數（Variables）

### 使用具有意義且可閱讀的名稱

**[⬆ 回到目錄](#目錄table-of-contents)**

### 相同類型的變數使用相同的名稱

**[⬆ 回到目錄](#目錄table-of-contents)**

### 使用可搜尋的名稱

* [buddy.js](https://github.com/danielstjules/buddy.js)

* [ESLint](https://github.com/eslint/eslint/blob/660e0918933e6e7fede26bc675a0763a6b357c94/docs/rules/no-magic-numbers.md)

**[⬆ 回到目錄](#目錄table-of-contents)**

### 使用可解釋的變數

`address.match(cityZipCodeRegex)` 取出了字串中的 city 與 zipCode 並以陣列（Array）的方式輸出。在糟糕的範例中，你不會知道哪個是 city，哪個是 zipCode。在適當的範例中，則清楚地解釋了。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免心理作用（Mental Mapping）

在糟糕的範例中，程式碼的作者認為從 `locations` 取出的都是地址，所以選用縮減後的 `l` 作為名稱。不過這只有作者自己這麼認為，其他人可不一定知道。避免「我認為」、「我以為」、「我覺得」，這樣的心理作用。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免使用不必要的描述（Context）

**[⬆ 回到目錄](#目錄table-of-contents)**

### 使用預設參數（Parameter）代替條件判斷（Conditionals）

使用預設參數較整潔，但請注意，當參數為 `undefined` 時才會作用，其他種類的虛值（Falsy）不會，像是 `''`、`false`、`null`、`0`、`NaN` 等。

預設參數非常好用，可以結合工廠模式做出很多應用。另外建議統一使用 `undefined` 代替 `null` 當作空值的回傳值。

此處原文為 **Arguments**，但是函數的參數定義應該為 **Parameter**，而呼叫函數時傳遞的引數才是 **Arguments**。

**[⬆ 回到目錄](#目錄table-of-contents)**

## 函數（Functions）

### 參數（Parameter） (少於 2 個較佳)

為了讓你可以清晰地表達，預期使用哪些物件的屬性（Properties），可以使用 ES2015/ES6 提供的解構（Destructuring）語法。使用這種語法有以下優點：

1. 函數需要物件的哪些屬性，可以像參數一樣清晰地表達。

2. 解構語法會複製來自物件的原始型態（Primitive），這能幫助你避免副作用（Side Effect）。注意！巢狀物件與陣列，並不會被解構語法複製。

3. 使用解構語法能讓物件屬性被程式碼檢查器（Linter）作用，提醒你哪些屬性未被使用到。

} = {}) { // 如未傳遞任何參數使用預設空物件，使用 `= {}` 可避免 TypeError: Cannot destructure property `...` of 'undefined' or 'null'.

想了解更多工廠模式與 ES6 的結合，可參考連結文章：[JavaScript Factory Functions with ES6+](https://medium.com/javascript-scene/javascript-factory-functions-with-es6-4d224591a8b1)。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 一個函數只做一件事情（單一性）

**[⬆ 回到目錄](#目錄table-of-contents)**

### 函數名稱應該說明它做的內容

建議函數命名以動詞開頭，像是 `doSomething()`、`setupUserProfile()`。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 函數應該只做一層抽象（Abstraction）

**[⬆ 回到目錄](#目錄table-of-contents)**

### 移除重複的（Duplicate）程式碼

正確的抽象化是非常關鍵的，這也是為什麼你應該遵循[類別（Classes）](#類別Classes)章節中，物件導向基本原則 SOLID 的原因。請小心，較差的抽象化會比重複的程式碼更糟！這麼說吧，如果你有把握做出好的抽象化，盡情放手去做。別讓程式碼出現重複的地方，不然你會需要修改更多的程式碼。

剛讀完這個原則時，我非常遵守，但是個人龜毛的個性，造成了不少麻煩，我會在開發時不斷的思考是否會出現了重複的程式碼，甚至考慮到了之後的重用性。代價就是過度設計（Over Engineering）造成功能開發窒礙難行，設計了良好架構，但實際上並未被使用到。最後總結了一個建議作為附加原則：一開始撰寫程式碼先以功能開發優先，當你發現有兩個以上的地方重複時，再來考慮要不要重構。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 使用 `Object.assign` 設定 `Object` 的預設值

**[⬆ 回到目錄](#目錄table-of-contents)**

### 不要使用旗標（Flag）作為參數

fs.create(`./temp/${name}`);

createFile(`./temp/${name}`);

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免副作用（Side Effects）

* 在沒有任何架構下，同時多個物件中分享共有狀態。

* 可變的狀態，且可以被任何人寫入

* 副作用發生的地方沒有被集中。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免副作用（Side Effects）第二部分

在 JavaScript 中，原始資料類型傳遞數值（Value），物件/陣列傳遞參照（Reference）。在本案例中，你的函數改變了購物車清單 `cart` 中的陣列，像是你增加了一個商品，其他使用購物車清單的函數將會被影響。這做法有好有壞，讓我解釋一下問題所在：

使用者按下付款按鈕後，將會呼叫 `purchase` 函數，產生一個網路請求傳送購物車清單陣列到伺服器。因為較差的網路連線，必須多嘗試幾次。此時使用者不小心又按下加入購物車按鈕，因為是參考的關係，請求將會送出新加入的商品。

較好的解決辦法是 `addItemToCart` 函數，執行前複製新的一份購物車清單，修改複製的資料後再回傳。這能確保其他的函數的購物車清單沒有任何機會被被參考所影響。

1. 當採用這種做法後，你會發現，需要修改輸入物件的情況非常少。大多數的程式碼可以在沒有副作用的情況下重構！

2. 複製大型物件，需要花費高昂的效能。幸好，我們有好的[函數庫](https://immutable-js.github.io/immutable-js/)，可以提升複製物件與陣列的速度與減少記憶體使用。

譯者這邊另外再提供一個案例，函數 `checkIs18Age` 用來檢查是否成年。第一個寫法中，引用了全域（global）變數 `minimum`，這功能看起來能正常運作沒問題，但是今天如果有其他函數 `setMinAge` 修改了全域變數 `minimum`，函數 `checkIs18Age` 將會因為副作用的關係變的無法預期，甚至失去它的作用。

較好的寫法是，採用純函數（pure function），使用一個可預期的變數，來避免副作用影響。

如果要複製巢狀結構，你需要深度複製。可以使用一些函數庫 [loadsh](https://lodash.com/) 的 `_.CloneDeep` 或是 [ramda](https://ramdajs.com/) 的 `clone`。或是使用 `JSON.parse(JSON.stringify(object))` 來實現。不過使用 JSON 的話，會失去 Function 的複製。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 別寫全域函數（Global Function）

在 JavaScript 中弄髒全域是個不好的做法，因為你可能會影響到其他函數庫或是 API。舉個例子，如果妳想要在 JavaScript 的原生陣列方法，擴展 `diff` 方法，用 B 陣列來去除 A 陣列中的元素（Element）。常見做法你可能會在 `Array.prototype` 中增加一個全新的函數，如果其他函數庫也有自己的 `diff` 實現的話將會互相影響。這就是為什麼我們需要使用 ES2015/ES6 的類別，來擴展的原因。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 偏好使用函數式程式（Functional Programming）設計代替命令式程式設計（Imperative Programming）

JavaScript 不是像 Haskell 一樣的函數式語言，但它具有類似特性。函數式程式設計更加乾淨且容易被測試。當你在寫程式時，盡量選擇此設計方式。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 封裝狀態（Encapsulate Conditionals）

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免負面狀態（Negative Conditionals）

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免狀態

當你第一次聽到時，這聽起來是不可能的任務。大部分的人會說：「怎麼可能不使用 `if` 語法？」事實上你可以使用多態性（Polymorphism） 達到相同的效果。第二個問題來了，「為什麼我們需要這樣做呢？」依據前面概念，為了保持程式碼的乾淨，當類別或是函數出現 `if` 語法，代表你的函數做了超過一件事情。記住，一個函數只做一件事情！

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免型別（Type）檢查：第一部分

JavaScript 為弱型別語言，代表函數應能處理任何型別的引數（argument）。有時這會帶給你一些麻煩，讓你需要做型別檢查。有很多方法可以避免這種問題發生，第一種就是統一所有的 API。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 避免型別檢查：第二部分

假設你需要型別檢查原始數值，像是字串與整數且你無法使用多態性處理，考慮使用 TypeScript 吧。他是提供標準 JavaScript 靜態類型的的最佳選擇。手動型別檢查需要很多額外處理，你得到的是虛假的型別安全，且失去的可讀性。保持你的 JavaScript 程式碼的整潔、寫好測試與足夠的程式碼審查（Code Review）。如果加上使用 TypeScript 會是更好的選擇。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 別過度優化

現代瀏覽器在運行時幫你做了很多優化。大多數的情況，你所做的優化都是在浪費你的時間。這裏有些很好的[資源](https://github.com/petkaantonov/bluebird/wiki/Optimization-killers)，去了解哪些優化是無用的。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 移除無用的程式碼（Dead Code）

**[⬆ 回到目錄](#目錄table-of-contents)**

## 物件（Objects）與資料結構（Data Structures）

### 使用 getters 與 setters

使用 `getters` 與 `setters` 來存取物件中資料，會比單純使用屬性（property）來的好。因為：

* 當你想要在取得物件屬性時做更多事情，你不用找出所有的程式碼修改。

* 透過 `set` 可以建立規則進行資料校驗。

* 封裝內部邏輯。

* 存取時增加日誌（logging）與錯誤處理（error handling）。

* 你可以延遲載入你的物件屬性，像是來自伺服器的資料。

**[⬆ 回到目錄](#目錄table-of-contents)**

### 讓物件擁有私有成員（members）