編程如何命名之三：糟糕的命名

    在此前的 編程如何命名（一、二）中，分別和大家聊到命名的一些規范，以及作家創作作品和編程的共同之處等話題，今天我們接著聊編程如何命名之三：糟糕的編程命名的特點有哪些，怎么避免。

運用正確意味著每一個詞都要用的恰到好處。

關于命名 ——菲利普·卡爾頓（Phil Karlton）

計算機科學有兩個艱難的事：

1. 緩存失效 ；
2. 命名。

關于不好的命名——劉易斯·卡羅爾（Lewis Carroll）

當我使用一個詞，胖墩兒說是一種輕蔑，當然這也正是我本事的意思-不多也不少。

愛麗絲奇遇記中，透過鏡子，愛麗絲究竟發現了什么？（1871）

故意無意義的名稱

理論上講，foo 僅僅作為一個占位符名稱（因為它無任何含義）

關于命名——薩姆·加德納（Sam Gardiner）

“如果你不知道一件事物叫什么，你就不知道它是什么。如果你不知道這是什么，你就不可能坐下來寫代碼。”

什么是最糟糕的變量名？

——data

什么是更糟糕的變量名？

data2

什么是第三糟糕的變量名？

data_2

縮寫容易引起歧義

以英文為例， char 是 character（字符） 還是 characteristic（特點）?

mod 的意思是 modify（修改） 還是 modulo （模）？

acc，pos 或者 auth 呢？

另外， fab 只是一個函數，?:A?B 。

而不是 fabulous （傳說）

允許一個例外：ID 作為 “identity” （身份）

一個字母太短 

局部變量：它的含義是什么？ 

var a = 42；

這一個是例外：
for  (int  i  =  1;  i  < 42; ++i)

改成 ii，jj，kk 也并不好

函數式編程：一個字母仍然太短

def modp[C](f: B1 => (B2, C), a: A1): (A2, C) = {
val (b, c) = f (get(a))
(set(a, b), c)
}

代碼出處：第 70 行

可以用特定含義的詞代替更多的詞

什么是 appointment_list？

A calendar？日歷？

什么是 company_person？ 

Employee 普通職員或者是 owner 老板？什么是 text_correction_by_editor？

只是一個 edit-編輯。

模糊語言是模糊的

艾倫·格林寫了一些模糊的詞，如：

InvoiceManager、TaskManager

Manager’ 非常不準確，其含義之一可能是你想要的字：

Bucket, Supervisor, Planner, Builder

原文地址：點擊查看

代碼里的模糊用語

get 在方法名的開頭只用于返回一個字段值。

如果不是這樣，或者從其他地方得到的數據， 用其他的詞：

fetch, find, lookup, create, calculate, derive, concoct.

錯誤的詞是錯的，同義詞易混淆

• order ≠ shipment
• carrier ≠ broker
• shipment ≠ transport leg
• shipment = consignment
• carrier = transporter
• transport leg = journey

Java 企業中間件示例 - Apache Camel

JF 杰微刊出品： Apache Camel- http://camel.apache.org

再探屬性訪問器 

在許多庫中， 這些方法名稱將是不可抗拒的，但不建議使用：

• getEven 
• getReal 
• getAround 
• getRoundTo 
• getRichQuick 
• getJoke

糟糕命名的總結 

• 無意義：foo；
• 太一般：data；
• 太短：a；
• 太長：text_correction_by_editor；
• 縮寫：acc；
• 模糊：InvoiceManager；
• 錯誤：order；
• 只是不好笑：startCamel

如何解決命名問題？以下四個方式供大家參考。

1. 成為一個更好的作家，
2. 提高你的詞匯量，
3. 采用更好的命名慣例。
4. 堅持。

一、成為一個更好的作家

命名只是寫作中的一部分，主要跟詞匯有關系，你也許記得學習詞匯是外語學習的一部分，沒有必要學習一門外語真是喜憂參半。

二、提高你的通用詞匯量

閱讀書籍，尤其是有趣的小說。和總是贏的人玩文字游戲 ，直到他們不再贏。

使用你的字典和知識庫，提高你的通用詞匯量。

“一個三明治走進一家酒吧。酒保說，對不起，我們不招待食物。”

講笑話

很多笑話都是文字游戲，這需要快速練習雙關語，雙關語重要的就是命名，因為他們依賴于雙重含義，發現雙重含義是避免歧義名字的基本技能。

三、采用更好的命名慣例

從含義和意圖開始；

使用有精確含義的詞語；

喜歡字少的名字；

不使用縮寫，除了 ID；

用代碼審查來改善命名；

請記住：“重命名”是簡單但最有效的重構，請使用它。

用更具體的詞替換含糊不清的詞：

克服重命名恐懼癥

比命名更困難的是重命名。

重命名需要變化，會話、新理解。

Refactor 是最安全的重構。

第 10 章：變量名的力量

第 2 章：有意義的名字

第 2 章：命名

• 學習特定領域的詞匯
• 在維基百科頁面搜索領域模型實體的相關概念名稱。
• 閱讀客戶領域的小說，學習他們的專業術語。
• 找出他們真正的含義。

對于命名，這里有 6 個技巧證明對我很有效：

1. 花很多時間來創造名字
2. 使用代碼審核
3. 不要猶豫重命名
4. 花很多時間在創造名字
5. 使用代碼審核
6. 不要猶豫重命名 

額外的收益

如果你成為一個更好的作家，你可以使用你的新技能 ——寫作。

“大多數的時候，程序員談論的關于代碼里的注釋大多數的事情都是他們沒寫注釋的借口。” @PeterHilton

關于注釋：基礎

1. 不要說代碼是做什么的——因為代碼已經說明了 。
2. 不要解釋復雜的邏輯——改進代碼使其更加清晰。
3. 不要添加太多注釋——混亂并且會過時。

解釋代碼為什么存在

即使完美的代碼也無法解釋它自己為什么存在。

• 什么時候我該使用這些代碼？
• 什么時候我不該使用這些代碼？
• 有沒什么備選的代碼，相比這些代碼？
• 發現哪些注釋很難寫，為什么？

如果注釋很容易寫，那么說明這些代碼不需要注釋。

為每個類和方法在開頭寫一句話注釋

“一個常見的謬誤是那些不好理解的代碼作者如何能在注釋里清晰地、明確地表達自己在做什么。”@KevlinHenney

承認編程（注釋）是一項專業技能

在一個多功能的開發團隊，并不是每個人都擅長視覺設計。寫代碼亦是如此。找出誰是更好的編程人員。并在寫注釋方面獲得幫助。

如何寫出更好的注釋（或總結）

1. 試著先寫出好的代碼。
2. 嘗試寫的一句話的注釋。
3. 重構代碼，直到注釋寫起來簡單。
4. 就是現在寫出好的注釋。
5. 不要忘了那些好的寫作規則（例如刪除不必要的注釋）。

四、堅持&總結

1. 命名是很難的 ；
2. 多從偉大的作家那得到靈感  ；
3. 閱讀小說，講笑話，玩游戲  ；
4. 擴充你的詞匯量 ；
5. 嘗試實際寫作；

每一個寫代碼的人，先從寫好注釋開始，請嘗試寫博客，甚至是寫一本書。

--

譯文鏈接：JF 杰微刊出品

[ 轉載請保留原文出處、譯者和譯文鏈接。]