【原】編寫(xiě)可讀性代碼

AiChinaTech 2019-08-16

展開(kāi)全文

作者：極鏈科技湯紅燕

什么叫可讀性代碼？

簡(jiǎn)單來(lái)說(shuō)，就是易于理解、耗腦時(shí)間少、可維護(hù)性較高的代碼。

編寫(xiě)可讀性代碼

把信息裝到名字里（一個(gè)好的名字可以承載很多信息）

1. 選擇專業(yè)的詞（避免“空洞”）

比如函數(shù)getUserInfo( ) 是用來(lái)獲取用戶信息，但是，是從接口中獲取的信息呢？還是在頁(yè)面已經(jīng)暴露的信息？看到的時(shí)候就會(huì)有疑問(wèn)。

命名的時(shí)候，如果是從互聯(lián)網(wǎng)中獲得，可以使用fetchUserInfo( )來(lái)表示。

2. 找到更有表現(xiàn)力的詞(更清晰、精確)

比如：search和 find 區(qū)別，再可以類似于表格數(shù)據(jù)的篩選，可以考慮用更準(zhǔn)確的詞匯去表示。

避免使用像tmp 和 retval 這樣泛泛的名字。

3. 使用具體的名字更細(xì)致地描述事物

對(duì)于一個(gè)變量包含十六進(jìn)制字符串，命名為 let id，但是為何不命名成 let hex_id?

如果你的變量時(shí)一個(gè)度量值的話，最好讓名字帶上它的單位。

4. 名字應(yīng)該有多長(zhǎng)

在編寫(xiě)代碼取名的時(shí)候總會(huì)有一些疑問(wèn)，我的定義名稱該多長(zhǎng)才合適？可以遵循以下幾點(diǎn)：

l 小作用域里可以使用短的名字；

l 首字母縮略詞和縮寫(xiě)（當(dāng)然是在成員能看懂的情況下 TBColor -> TextBackgroundColor）；

l 丟掉沒(méi)用的詞（no-padding-all -> no-padding）；

l 利用名字的格式來(lái)傳遞含義（比如所有的class 是class-name, id 是 id_id）；

不會(huì)讓人誤解的名字

常用的filter() 命名，如果新同學(xué)看到，可能會(huì)產(chǎn)生疑問(wèn)，這是過(guò)濾掉滿足要求的值呢還是不滿足要求的？
為了便于處理以上情況，有以下幾點(diǎn)建議：

l 使用 min 和 max 來(lái)表示（包含）極限

l 使用 first 和 last 來(lái)表示包含的范圍

l 使用 begin 和 end 來(lái)表示包含/排除范圍

l 給布爾值命名

對(duì)于語(yǔ)句 bool read_password = true 是我們已經(jīng)讀取密碼，還是我們需要讀取密碼?

這時(shí)候可以用 need_password 或 user_is_authenticated 這樣的名字來(lái)代替；

像 is 、has 、can或should這樣的詞，就可以把布爾值變得更明確。

審美

代碼的審美，確切地說(shuō)，有三條原則：

1. 使用一致的布局，讓讀者很快就習(xí)慣這種風(fēng)格。

2. 讓相似的代碼看上去相似。

3. 把相關(guān)的代碼行分組，形成代碼塊。

該寫(xiě)怎樣的注釋

1. 從代碼本身快速推斷出事實(shí)的不需要注釋

2. 不要為了注釋而注釋

3. 不要給不好的名字加注釋（不如改名字）

4. 加入“導(dǎo)演評(píng)論”，你可以在代碼中加入注釋來(lái)記錄你對(duì)代碼有價(jià)值的見(jiàn)解。

5. 為代碼中的瑕疵寫(xiě)注釋

6. 給常量加注釋（有些常量不需要注釋，因?yàn)樗鼈兊拿忠呀?jīng)很清楚，但很多常量可以通過(guò)加注釋得以改進(jìn)）

7. 站在讀者的角度，“全局觀”注釋

寫(xiě)出言簡(jiǎn)意賅的注釋

1. 讓注釋保持緊湊

2. 避免使用不明確的代詞（如it,this等）

3. 潤(rùn)色粗糙的句子

4. 精確地描述函數(shù)的行為

比如用輸入/輸出例子來(lái)說(shuō)明特別的情況

下面是一個(gè)用來(lái)移除部分字符串的通用函數(shù)：

5. 聲明代碼的意圖

對(duì)于“具名函數(shù)參數(shù)”的注釋，就是像 C# Python 這類語(yǔ)言的命名函數(shù)參數(shù)，讓每個(gè)參數(shù)的意義更加明確。

比如：

6. 采用信息含量高的詞

l 避免使用代詞

l 盡量精確描述函數(shù)的行為

l 精心挑選輸入/輸出的例子

l 聲明代碼的高層次意圖，而非明顯的細(xì)節(jié)

l 用嵌入注釋解釋難以理解的函數(shù)參數(shù)

l 用含義豐富的詞語(yǔ)

簡(jiǎn)化循環(huán)和邏輯

1. 把控制流變得易讀

l 條件語(yǔ)句中參數(shù)的順序

比較左側(cè)： “被詢問(wèn)”的表達(dá)式，它的值傾向于不斷變化

比較右側(cè)：用來(lái)做比較的表達(dá)式，它的值更傾向于常量

l if/else 語(yǔ)句塊的順序

首先處理正邏輯而不是負(fù)邏輯

再處理簡(jiǎn)單的情況

最后處理有趣的或者是可疑的情況

l ?: 表達(dá)式, 只有在簡(jiǎn)單的情況下使用

l 避免 do/while 循環(huán)

l 從函數(shù)中提前返回

l 最小化嵌套

l 減少循環(huán)內(nèi)嵌套

2. 拆分超長(zhǎng)表達(dá)式

l 用做解釋的變量

l 總結(jié)變量(用一個(gè)短很多的名字來(lái)代替一大塊代碼，這就是總結(jié)變量)

l 拆分巨大的語(yǔ)句

比如：

顯而易見(jiàn)，這段代碼邏輯很清晰，但是看著太復(fù)雜，下面改掉：

這樣做有很多好處：

- 避免輸入的錯(cuò)誤。

- 縮短了行的寬度，更容易快速閱讀。

- 如果類名字改變了，只需要改變一個(gè)地方就行了。

3. 變量與可讀性

l 減少變量，即那些妨礙的變量。通過(guò)離開(kāi)處理結(jié)果來(lái)消除“中間結(jié)果”的變量。

l 減少每個(gè)變量的作用域，越小越好。

l 只寫(xiě)一次的變量更好，那些只設(shè)置一次值的變量（或者 const 、final、常量）使得代碼更容易理解。

4. 抽取不相關(guān)的子問(wèn)題

l 積極地發(fā)現(xiàn)并抽取不相關(guān)的子邏輯：

- 看看某個(gè)函數(shù)或代碼塊，問(wèn)問(wèn)自己：這段代碼的高層次的目標(biāo)是什么？

- 對(duì)于每一行代碼，問(wèn)下：它是為了目標(biāo)而寫(xiě)的么？

- 如果足夠的行數(shù)在解決不相關(guān)的子問(wèn)題，試圖抽取代碼到獨(dú)立函數(shù)中。

l 純工具代碼（封裝共用的函數(shù)）

l 其他多用途代碼（比如頁(yè)面上數(shù)據(jù)邏輯代碼）

l 創(chuàng)建大量通用代碼（組件）

- 通用代碼很好，因?yàn)?/span>“完全地從項(xiàng)目的其他部分中解耦出來(lái)”。

l 項(xiàng)目專有的功能（私有組件）

l 簡(jiǎn)化已有接口，按需重塑接口

5. 一次只做一件事

應(yīng)該把代碼組織得一次只做一件事情。如何給代碼整理碎片，下圖演示了這個(gè)過(guò)程：

6. 把想法變成代碼

如果有好的想法，則可以實(shí)現(xiàn)為代碼，但需要注意以下幾點(diǎn)：

l 清楚地描述邏輯

l 可了解相關(guān)函數(shù)庫(kù)，以便減少代碼量

l 把這個(gè)方法應(yīng)用于更大的問(wèn)題

l 用自然語(yǔ)言描述解決方案

l 遞歸地使用這種方法

7. 少寫(xiě)代碼

“最好讀的代碼就是沒(méi)有代碼”，在收到一個(gè)需求的時(shí)候，要質(zhì)疑和拆分你的需求，用小的代碼庫(kù)，去替代大的代碼庫(kù)；刪除沒(méi)有用的代碼，簡(jiǎn)化實(shí)現(xiàn)過(guò)程；熟悉你周邊的庫(kù)，了解最優(yōu)庫(kù)；對(duì)于一些庫(kù)的重用，可以極大的節(jié)省時(shí)間。