如何編寫高質量的 JS 函式（2） -- 命名/註釋/魯棒篇

阿新 • • 發佈：2019-09-02

本文首發於 vivo網際網路技術微信公眾號
連結：https://mp.weixin.qq.com/s/sd2oX0Z_cMY8_GvFg8pO4Q
作者：楊昆

上篇《如何編寫高質量的 JS 函式（1） -- 敲山震虎篇》介紹了函式的執行機制，此篇將會從函式的命名、註釋和魯棒性方面，闡述如何編寫高質量的 JS 函式。

（一）函式命名

一、目前前端的函式命名存在什麼問題

從上圖可以知道，命名和快取是電腦科學中的兩大難題。

本文要說的函式命名，雖然涉及到的範圍較窄，但思想都一樣，完全可以借鑑到其他的形式中。

之前閱讀過程式碼大全中變數的相關章節，也針對性的瞭解過一些原始碼，根據我的經驗總結，目前函式命名除了業界標準的問題外，還存在一些細節的問題，比如：

中英語言的差異性

不懂得從多維度去提升命名的準確性（如何從多維度去提升命名的準確性）

不會使用輔助工具（如何使用輔助工具）

下面進行簡明扼要的分析。

二、漢語和英語的差異性

1、為什麼不能用漢語方式命名呢？

漢語拼音存在多義性；漢字翻譯的輔助工具還不夠普及，因此不能用漢語方式命名。

2、用英語時遇到的困難

最大的難點在於語法的正確使用場景。

舉個例子， react 的生命週期，如下：

componentDidMount

componentWillReceiveProps

shouldComponentUpdate

很多人都會有疑問，為什麼用 did 和 will 。

三、如何讓命名有英語 style

舉個例子：

componentDidMount 是 react 等生命週期的鉤子，但是為什麼要這樣命名？

componentWillReceiveProps 為什麼要這樣命名？

答案就在下圖：

注意上圖中的 did 代表一般過去時，will 代表一般將來時。

然後我們百科一般過去式和一般將來時，如圖所示。

（1）一般過去時：

（2）一般將來時：

看上圖的紅箭頭，did 表示一般過去時，時是指動作發生的時間，用在這裡，突出了鉤子的含義，一旦 mount 成功就執行此函式。will 同理。

四、通過函式返回結果來命名

這是個小特性，比如 shouldComponentUpdate ，為什麼 should 放在最前面。

因為這個函式返回的值是布林值。那麼我們可以理解為這是個問句，通過問句的形式來告訴我們，這裡具有不確定性，需要根據返回值來判斷是否更新。

五、藉助工具

1、藉助谷歌翻譯

2、藉助 codelf

這是一個神器，用來搜尋各種開源專案中的變數命名，以供參考。

地址：unbug.github.io/codelf/

對應名字的 VSCODE 外掛也有。

六、如何避免函式命名的多義性和不可讀性

ramda 原始碼中的一個函式，程式碼如下：

var forEachObjIndexed = _curry2(function forEachObjIndexed(fn, obj) {
var keyList = keys(obj);
var idx = 0;
while (idx < keyList.length) {
var key = keyList[idx];
fn(obj[key], key, obj);
idx += 1;
}
return obj;
});
export default forEachObjIndexed;

這個函式叫 forEachObjIndexed ，程式碼中看不出這個函式的命名含義，只能從從原始碼裡面的函式註釋中找答案。

函式註釋如下圖：

由此知道，如果函式命名存在困難，可以通過註釋的方式，將函式的整體介紹和說明輸出文件來解決這個問題。

七、函式命名的分類

函式命名很普遍的一個現象就是帶各種字首的函式名，如下：

- $xxx()
- _xxx()

這種帶各種字首的函式名，看起來並不好看還彆扭。核心原因是 JS 語言不支援私有變數，導致只能使用 _ 或者 $ 來保證相應的對外不可****見。

所以我把前端的函式命名分為兩大類，如下：

第一類：不想暴露給外部訪問的函式(比如只給內部使用)

第二類：暴露給外部訪問的函式(各種功能方法)

而Symbol 初始化的函式命名是一種特例，程式碼如下：

const ADD = Symbol('add')

[ADD](a, b) {
console.log('a + b')
}

八、總結

總結一下最佳實踐：

多學習初中高中英語語法，開源專案中的函式命名沒有那麼難理解，通過語法的學習和藉助工具，函式命名基本可以解決，如果遇到無法清晰描述所寫函式的目的的命名時，請務必給函式寫上良好註釋，不管函式名字有多長多難懂，只要有良好的註釋，那就是可以接受的一件事情。

（二）函式的註釋

一、有名的npm包的一些註釋風格

函式註釋，一方面提高了可讀性，另一方面還可以生成線上文件。

一個高質量的函式，註釋少不了，但是這並不代表所有的函式都需要註釋。富有富的活法，窮有窮的瀟灑，重要或者複雜的函式，可以寫個好註釋；簡單或者不重要的函式，可以不寫註釋或者寫一個簡單的註釋。

那麼，目前函式的註釋都有哪幾種方式呢？

1、egg.js 的註釋風格

從圖中可以看到 egg.js 的入口檔案的註釋特點是簡單整潔。

繼續看下圖：

這是一個被抽象出來的基類，展示了作者 [Yiyu He] 當時寫這個類的時候，其註釋的風格有以下幾點：

第一點：建構函式的註釋規則，表示式語句的註釋規則。

第二點：註釋的取捨，有一些變數可以不用註釋，有些要註釋，不要有那種要註釋就要全部註釋的思想。

再看兩張有趣的圖片：

看上面兩張圖的箭頭，指向的都是同一個作者 [fengmk2] 。他的函式註釋規則，第一張圖沒有空格，第二種有空格，還有對返回的 this 的註釋，比如很多人習慣將 this 直接註釋成 Object 型別。

2、lodash.js

說到函式註釋，就不能不說到 lodash.js 。由於篇幅有限，本文就不做相應介紹了，大家自行按照上面的方式去了解。

二、通過註釋生成線上文件的思考

有人說註釋要很規範，方便給別人，比如用 jsdoc 等。我的觀點是，對一些不需要開源的 web 專案，沒有必要用 jsdoc ，理由如下：

1.繁瑣，需要按照 jsdoc 規則來。

2.個人認為，jsdoc 有入侵性，文件規則需要寫在程式碼中。

如果要寫註釋說明手冊，對於大型專案，我推薦使用 apidoc ，因為 apidoc 入侵性不強，不要求把規則寫在程式碼中，可以把所有規則寫到一個檔案中。

但是一般小專案，沒有必要單獨寫一份 api 文件。如果是開源的大型專案，首先需要考慮是否有開源的官方網站，你會看到網上的一些開源專案官網好像很酷，其實這個世界上不缺的就是輪子，你也可以很快的做出這樣的網站，

下面我們來看看是如何做到的。

首先看一下 taro 原始碼，如下圖：

這裡就是生成一個靜態網站的祕密，執行 npm run docs 就可以。用的是 docusaurus 包。

從上圖中可以知道，文件的內容，來源於 docs 目錄，裡面都是 md 檔案，開源專案的文件說明都在這裡。

當然也有把對應的文件直接放到對應的程式碼目錄下的，比如 ant-design 如下圖：

就是直接把文件放在元件目錄下了。

從這裡我們可以知道，目前流行的開源專案的官方網站是怎麼實現的，以及文件該怎麼寫。

三、我個人的註釋習慣

下面說說我本人對函式註釋(只針對函式註釋)的一些個人風格或者意見。

1、分享 VSCode 關於註釋的幾個工具

Better Comments 給註釋上色

Document This 自動生成註釋

TODO Highlight 高亮 TODO ，並可以搜尋所有 TODO

下面是一張演示圖：

2、寫和不寫註釋的平衡

我的觀點是不影響可讀性，複雜度低，對外界沒有過度干涉的函式可以不寫註釋。

3、表示式語句的註釋

函式內，表示式語句的註釋可以簡單點。如下圖所示，// 後面加簡要說明。

function add(a, b) {
// sum ....
let sum = a + b
}

4、TODO 註釋

function say() {
// TODO: 編寫 say 具體內容
console.log('say')
}

5、FIXME 註釋

function fix() {
// FIXME: 刪除 console.log方法
console.log('fix')
}

6、函式註釋

一般分為普通函式和建構函式。

（1）普通函式註釋：

/**
* add
* @param {Number} a - 數字
* @param {Number} b - 數字
* @returns {Number} result - 兩個整數之和
*/
function add(a, b) {
// FIXME: 這裡要對 a, b 引數進行型別判斷
let result = a + b
return (result)
}

（2）建構函式註釋：

class Kun {
/**
* @constructor
* @param {Object} opt - 配置物件 
*/
constructor(opt = {}) {
// 語句註釋
this.config = opt
}
}

7、總結

從開源專案的程式碼中可以發現，在遵守註釋的基本原則的基礎上，註釋的風格多種多樣；同一個作者不同專案的註釋風格也有所差別，但我會盡可能的去平衡註釋和不註釋。

（三）函式的魯棒性(防禦性程式設計)

下圖是一個段子：

最後一句，測試測了那麼多場景，最後酒吧還是炸了，怎麼回事？

從中我們可以看出，防禦性程式設計的核心是：

把所有可能會出現的異常都考慮到，並且做相應處理。

而我個人認為，防禦性的程度要看其重要的程度。一般來說，不可能去處理所有情況的，但是提高程式碼魯棒性的有效途徑就是進行防禦性的程式設計。

一、一個專案的思考

我曾經接手過一個需求，重寫微信小程式的登入註冊繫結功能，並將程式碼同步到其他小程式(和其他小程式的開發進行程式碼交接並協助 coder 平穩完成版本過渡)。

這個專案由於使用者的基數很大，風險程度很高，需要考慮很多場景，比如：

是否支援線上版本回退，也就是需要有前端的 AB 版本方案(線上有任何問題，可以快速切到舊登入方案)
需要有各種驗證：圖形驗證碼、簡訊驗證碼、ip 、人機、裝置指紋、風控、各種異常處理、異常埋點上報等。
程式碼層面的考慮：通過程式碼優化，縮短總的響應時間，提高使用者體驗。
如何確保單個節點出問題，不會影響整個登入流程。

如何去合理的完成這個需求還是比較有難度的。

PS: 關於第4點的如何確保單個節點出問題，不會影響整個登入流程，文末有答案。

下面我就關於函式魯棒性，說一說我個人的一些看法。

二、前端函式魯棒性的幾種方式

1、入參要魯棒性

在 ES6+ 到來後，函式的入參寫法已經得到了質的提高和優化。看下面程式碼：

function print(obj = {}) {
console.log('name', obj.name)
console.log('age', obj.age)
}

print 函式，入參是 obj 通過 obj = {} 來給入參設定預設的引數值，從而提高入參的魯棒性。

同時會發現，如果入參的預設值是 {} ，那函式裡面的 obj.name 就會是 undefined ，這也不夠魯棒，所以下面就要說說函式內表示式語句的魯棒性了。

2、函式內表示式語句要魯棒性

繼續上個例子：

function print(obj = {}) {
console.log('name:', obj.name || '未知姓名')
console.log('age:', obj.age || '未知年齡')
}

如果這樣的話，表示式語句變得比較魯棒性了，但還不夠抽象，我們換種方式稍微把表示式語句給解耦一下，程式碼如下：

function print(obj = {}) {
const { name = '未知姓名', age = '未知年齡' } = obj
console.log('name:', name
console.log('age:', age)
}

上述程式碼其實還可以再抽象，比如把 console.log 封裝成 log 函式，通過呼叫 log(name) ，就能完成 console.log('name:', name) 的功能。

3、函式異常處理的兩個層面

防患於未然，從一開始就不要讓異常發生。

異常如果出現了，該怎麼去處理出現的異常。

那如何去更好的處理各種異常，提高函式的魯棒性呢，我個人有以下幾點看法。

4、推導一下 try/catch 的原理

js 在 node.js 提供的執行時環境中執行，node.js 是用 C++ 寫的。C++ 有自己的異常處理機制，也是有 try/catch 。即 js 的 try/catch 的底層實現是直接通過橋，呼叫 C++ 的 try/catch 。

而 C++ 的 try/catch 具有一些特性，如try/catch 只能捕捉當前執行緒的異常。這樣就解釋了為什麼 JS 的 try/catch 只能捕捉到同步的異常，而對於非同步的異常就無能為力了(因為非同步是放在另一個執行緒中執行的)。

這裡是我的推導，不代表確切答案。

這裡我推薦一篇部落格：《C++中try、catch 異常處理機制》，有興趣的可以看看。

5、合理的處理異常

第一個方法：如果是同步操作，可以用 throw 來傳遞異常

看下面程式碼：

try {
throw new Error('hello godkun, i am an Error ')
console.log('throw 之後的處程式碼不執行')
} catch (e) {
console.log(e.message)
}

首先 throw 是以同步的方式傳遞異常的，也就是 throw 要和使用 throw 傳遞錯誤的函式擁有相同的上下文環境。

如果上下文環境中，都沒有使用 try/catch 的話，但是又 throw 了異常，那麼程式大概率會崩潰。

如果是 nodejs ，此時應該再加一個程序級的 uncaughtException 來捕捉這種沒有被捕捉的異常。通常還會加上 unhandledRejection 的異常處理。

第二個方法：如果是非同步的操作

有三種方式：

使用 callback ，比如 nodejs 的 error first 風格。
對於複雜的情況可以使用基於 Event 的方式來做，呼叫者來監聽物件的 error 事件。
使用 promise 和 async/await 來捕捉異常。

怎麼去選擇哪個方式呢？依據以下原則：

簡單的場景，直接使用 promise 和 async/await來捕捉異常。
複雜的場景，比如可能會產生多個錯誤，這個時候最好用 Event 的方式。

第三個方法：如果既有非同步操作又有同步操作

最好的方式就是使用最新的語法：async/await 來結合 promise 和 try/catch 來完成對既有同步操作又有非同步操作的異常捕捉。

第四個方法：處理異常的一些抽象和封裝

對處理異常的函式進行抽象和封裝也是提高函式質量的一個途徑。如何對處理異常進行抽象和封裝呢？有幾個方式可以搞定它：

第一種方式：對 nodejs 來說，通常將異常處理封裝成中介軟體，比如基於 express/koa 的異常中介軟體，通常情況下，處理異常的中介軟體要作為最後一箇中間件載入，目的是為了捕獲之前的所有中介軟體可能出現的錯誤。
第二種方式：對前端或者 nodejs 來說，可以將異常處理封裝成模組，類似 Event 的那種。
第三種方式：使用裝飾器模式，對函式裝飾異常處理模組，比如通過裝飾器對當前函式包裹一層 try/catch 。
第四種方式：使用函數語言程式設計中的函子( Monad )等來對異常處理進行統一包裹，這裡的 Monad 和 try/catch 在表現上都相當於一個容器，這是一個相當強大的方法。從 Monad 可以擴展出很多異常處理的黑科技，但是我建議慎用，因為不是所有人都能看懂的，要考慮團隊的整體技術能力，當然一個人的話，那就隨便嗨了。

合理的處理異常，根據具體情況來確定使用合理的方式處理異常

這裡推薦一篇部落格：《Callback Promise Generator Async-Await 和異常處理的演進》

三、如何確保單個節點出問題，不會影響整個登入流程

比如登入流程需要4個安全驗證，按照通常的寫法，其中一個掛了，那就全部掛了，但是這不夠魯棒性，如何去解決這個問題呢。

主要方案就使用將 promise 的鏈式寫法換一種方式寫，以前的寫法是這樣的：

虛擬碼如下：

auth().then(getIP).then(getToken).then(autoLogin).then(xxx).catch(function(){})

經過魯棒調整後，可以改成如下寫法：