給代碼起個好名字

在公司裏，我有個不怎麼經常使用的綽號，叫「算命先生」——幫別人起名字的，準確說，幫別人的代碼起名字，包括項目名，目錄名，類名，屬性名，方法名，變量名等。事實上，我也確確實實幫過別人起名字，起名字總歸有些套路，要避開一些坑，一個好的名字就是一個成功的開始，反之可能後面會帶來不少困擾。我跟同事說，好的名字讓你行走江湖更容易，你看「葉孤城」、「西門吹雪」、「東方不敗」這些名字一聽就知道是絕世高手，但你試着叫「王霸天」、「李二狗」、「牛春花」，不是活不過兩集就是連上鏡的機會都沒有。

 

下面分享一些我的的經驗及見解，全部的觀點都並不是絕對，當你看完整篇文章後確定也深覺得然，我所提出的這些套路也是爲了這麼個中心服務的： 使得代碼更有條理和可讀性。

1，用英文，別用中文，別用拼音，更加別用拼音縮寫

這應該是老生常談了。

 

C#/Java語言挺神奇，能夠用中文作標識符，好比你建立一個類，叫「貨物訂單」，徹底沒問題，但有人嘗試過以後就很快放棄了，由於可讀性實在太差了，另外在作代碼搜索的時候，輸入中文自己就比英文要慢，英文還方便用正則等去匹配，中文在這方面操做起來就比較困難，若是你還想把代碼移植到別的語言去，就更加不能用中文了。

 

拼音也別用，由於拼音你不念出來的話你每每不知道它想表達什麼意思，漢語拼音中還有聲調，而代碼中又表示不了，有時候真能讓閱讀者一臉懵逼。

 

那拼音縮寫就更加不用說了，我維護過一些老古董代碼就全是拼音縮寫，噁心+崩潰。

好	很差	很差	垃圾
GoodsOrder	商品訂單	ShangPinDingDan	Spdd
InventoryCheck	庫存盤點	KuCunPanDian	kcpd
InvoiceManagement	發運單管理	FaYunDanGuanLi	fydgl
RouteConfiguration	路由配置	LuYouPeiZhi	lypz

2，不要拼寫錯誤

這不是廢話麼？但也不知道是因爲不當心仍是英文水平太差，我遇到的代碼中的拼寫錯誤實在太多太多了，更有甚者把公司的名稱都寫錯的。若是你哪天用微軟的代碼，發現命名空間是：Micorsoft.Extensions.Logging，你會有什麼感覺？

 

寫代碼和作別的事情同樣，也須要用心，遇到不肯定的東西時，查一下，問一下，如發現本身以前的問題，要及時修正。

 

隨便列舉一些拼寫錯誤(跟技術無關，純粹看英語水平和仔細程度)

錯誤	正確	描述
lable	label	字母先後寫錯是常發生的事情
catched	caught	catch的過去分詞爲不規則
loging	logging	注意添加-ing的特例
IsEnable	IsEnabled	Enabled纔是形容詞，才能用系動詞
登錄	登陸	你覺得中文的錯別字就少了？
SingleBox	PackingList	本公司的梗，「發票箱單」，某同事翻譯成了Single(單)Box(箱)，奇葩

3，用名詞充當類名

類，一般表示一個數據實體，或者一系列數據與方法的封裝，大多時候是應當使用名詞的。下面是一些例子：

名稱	不太好	不錯
登陸信息	Login(這是動詞唉)	LoginReq(Req表示Request，一看就知道這是個登陸請求) 或LoginUi，後綴Ui表示UI層使用的類。
出庫訂單	Order(太廣泛了，且order是SQL的關鍵字，容易帶來一些不便)	OutBoundOrder
全局變量	Global(這是形容詞)	GlobalData，GlobalAppConfig等
總線請求類	BusRequest(這是動詞)	BusRequester(請求者，湊合，但仍不太好) BusReqManager(這個名字明顯更好)

4，不要使用太廣泛的名詞充當類名

 如Configuration，這個詞表示配置，你打算建立這麼一個類表示系統的配置信息，並提供相應方法。但你要注意了，一個較大的系統裏一般有不少不少的配置，好比程序的全局配置，入庫規則配置，出庫規則配置，外部接口訪問配置，日誌配置……若是你全都叫Configuration，你極可能三天兩頭被本身搞懵。那怎麼辦？寫具體點不就好了麼？

很差	好一點	說明
Configuration	GlobalApplicationConfiguration InBoundConfiguration ExteralApiConfiguration LoggingConfiguration	起碼更具體了
Param (某個外部API的參數)	GenericExternalApiParam	標識符命名不必再從技術上描述它是什麼東西，正如你不須要寫完「int i=1」後加個註釋「定義整型變量i並賦值1」，要使得名字符合業務邏輯

固然，也有例外的狀況，好比個人項目中一般有個類叫「Fmt」，很是簡單，其實就是Format的簡寫，這個類不涉及到具體的業務邏輯，只是用來對時間日期和數值進行一些格式化操做，因此能夠起個這麼簡的名字。

5，適當的簡寫與約定俗成的縮寫

 上面起的名字你是否是以爲太長了？那可不能夠縮寫一些？那是確定的，代碼中，咱們存在着不少約定俗成的「單詞」，舉個最簡單的例子：ID，ID是Identity的簡寫，爲何咱們如今都知道？由於已經「約定俗成」了，這種例子還不少，我隨便舉一些：

本來	簡寫
participant	ptcp
application	app
description	desc
abbreviation	abbr
configuration	config或cfg
Machintosh	Mac

縮寫的規則一般是取前面幾個字母，但也有例外的，如前面提到的participant，若是縮寫爲part的話，因爲part是另一個單詞，容易引發誤會，因此就取participant中的幾個與發音相關的輔音字母來組成簡寫，因此configuration也能夠簡寫爲cfg，關鍵是要你們都承認。

6，約定俗成的縮寫

 英文中的縮寫實在太多了，若是沒有這些縮寫，用英語就簡直沒法交流，我並不誇張，隨便寫幾個縮寫的例子：

英文縮寫	英文全稱	中文
NASA	National Aeronautics and Space Administration	美國國家航空和宇宙航行局
BASIC	Beginner's All-purpose Symbolic Instruction Code	初學者通用符號指令代碼
EPROM	Electrically Programmable Read-Only-Memory	電可編程序只讀存儲器
JSON	JavaScript Object Notation	JavaScript對象表達式
ASN	Advanced Shipment Notice	預到貨通知單
DN	Delivery Number	運單號

如今你有問題了：「你前面剛說拼音縮寫‘垃圾’，爲何這裏又容許英文縮寫？」Good question，我這樣說吧：關鍵點在於約定俗成，你們承認，英文中的縮寫詞常常能本身成爲一個單詞，如ROM，咱們都直接念它「[rɔm]」，而不是「R-O-M」，你們都已經承認了「ROM」這個單詞了，這就能夠了。文章一開始我也說了，全部這些，都是爲了這個中心服務的：使得代碼更有條理和可讀性！因此我提出的建議也只是建議，不是鐵律。

 

這麼說的話，咱們是否是拼音縮寫在某些時候也能用一下？——沒錯，咱們公司常常就用Shwgq來表示「上海外高橋」，一來「上海外高橋」是專有名詞，只能寫拼音，二來公司同事都已經承認了，因而就能夠愉快地使用了，但我又要說回來，這個是個特例，千萬不要濫用。

7，駝峯命名法

 先問這麼一個問題：UserID好，仍是UserId好？

 

也許你有你的見解，而個人見解很明確：UserId好，由於它很好地區分出了ID這個「單詞」，前面說了ID是Identity的簡寫，但承認的人多了以後，ID自己就成爲了一個單詞，根據駝峯命名法的規則，單詞首字母大寫，其他小寫，所以應當寫UserId，可能一開始感受有點不習慣，但後面很快就能適應。

 

另外還有一個問題：UserName好，仍是Username好？

 

按規則應該是Username，由於這自己就是一個單詞，但因爲歷史緣由，在個人項目裏面，一概寫成UserName，之前寫錯了，慣性太大，改不了，就當是User和Name兩個單詞拼成的吧——看吧，兵無常勢水無常形，要靈活應變。

 

另外還要注意一點，用駝峯命名法的時候，避免連續出現大寫字母，不然很影響代碼可讀性。

8，適當使用後綴區分

 有時候實在不知道怎麼起名字，如登陸，叫「Login」，這個也許表示客戶端向服務器提交的登陸請求，但也能表示服務器處理好登陸請求後返回給客戶端的信息， 怎麼辦？

 

個人辦法是加上後綴做區分：

登陸	登陸請求	登陸響應
Login	LoginReq	LoginResp

這樣就很是清晰了，Req即Request，Resp即Response，這種方法還能把Login這個動詞變做一個名詞，太好用了。

 

再好比，員工信息，叫EmployeeInfo，它能夠是來自客戶端的提交的信息，根據系統的分紅架構，這個Model須要從UI層傳遞到業務邏輯層，但這兩個層的EmployeeInfo類是有差異的，難道都要叫EmployeeInfo，只用命名空間來區分嗎？個人「套路」通常以下：

員工信息	UI層的員工信息	業務邏輯層的員工信息
EmployeeInfo	EmployeeInfoUi	EmployeeInfoBl 或 EmployeeInfo

UI層加上Ui後綴(根據前面提到的規則，i小寫)，業務邏輯層能夠加上Bl，也能夠不加，由於UI層加了，就表示能夠區分開來了。

9，用謂賓結構來命名方法

 方法表示某個執行動做，一般都是謂賓結構，爲何把主語省掉了？由於主語100%是調用者，根本不用問。這是一些例子：

方法	好
報關單做廢	CancelDeclaration
檢驗是否存在	CheckIfExisting
出庫確認	ConfirmOrder
刪除核放單	DeleteGatebill

沒太多好說的，在動詞的選擇方面，有如下這些經常使用動詞：

動詞	英文
建立	Create
增長	Add(注意跟「建立」語義上的差別)
更新/編輯	Update/Edit
刪除/移除	Delete/Remove
清空	Clear/RemoveAll
獲取/設置	Get/Set
發送/接受	Send/Receive
檢查是否XXX	CheckIf
生成	Generate
計算	Calculate
上傳/下載	Upload/Download
萬能動詞	Do/Make

還有不少，我不列了，不然就真的變成上英語課了，英語和漢語同樣，同義詞不少，但語義上經常會有些微小的差別，好比建立和增長，建立一個新用戶，這是一個從無到有的過程，因此一般用Create，而將這個建立好的用戶加到開發部門中去，則是Add的概念，開發部門原本就存在的，只是多了一我的，你們去體會體會。咱們在選動詞的時候一般會選比較符合英文文法的詞，而不能太過於「技術」，如選擇Create而不是SQL的Insert，由於Insert是個數據庫技術中的概念，而不是業務邏輯上的概念，再如選擇Send而不是Post，也是同樣道理，但這個並不絕對，假如你開發的是一個網絡訪問的基礎庫，那麼你徹底能夠用Post啊，由於這個情形下，Post自己就更能描述業務邏輯。

 

實在不知道怎麼選動詞的話能夠考慮下Do和Make這兩個萬能動詞，DoXxx，能夠表示幹任何事情，而Make同樣很萬能，Trump大帝競選美國總統的時候口號不是「Make American Great Again」麼？使或讓的意思，放在不少場合都適用，再好比Make money，「賺錢」的意思。

10，複數與列表

 有次我複查代碼，看到一個「訂單」中的「訂單明細」是這麼命名的：OrderLineCounts。莫名其妙，這根本不通啊。

 

用「Line」表示明細是咱們公司的約定俗成，一個訂單主檔中帶若干訂單明細，我說用來表示這種明細列表一般有兩種方法，一種是用複數，另外一種加個List後綴：

 

不通	通	通
OrderLineCounts	OrderLines	OrderLineList

 

這裏還要注意一下：

1，不是全部名詞都有複數形式，英語中有些詞不可數對不？因此加個List後綴可能更通用一些

2，不是全部可數名詞均可以直接加s變成複數形式，如Data，其複數形式應該是Datum，不要寫Datas

3，有些單詞單複數同形，如Goods，商品，複數也是Goods，不要寫做Goodses

最後

 講一個東西，叫「破窗效應」(Broken Window Theory)，我是許多年前在《程序員修煉之道》這本書上看到的(這本書強烈推薦一下)，這個道理很簡單，就是說若是你一開始對系統中出現的破敗視而不見的話，更多的破敗就會出現，直到事態不可挽回。你對代碼的命名不認真，馬馬虎虎，致使同事看不懂，同事誤會了你的意思，跟着你亂命名，你再次接手這代碼的時候，已經凌亂不堪，你感受已經很難維護，因而更加得過且過，直到程序沒人再敢去碰。

 

「宇宙的熵在升高，有序度在下降，像平衡鵬那一望無際的黑翅膀，向存在的一切壓下來，壓下來。但是低熵體不同，低熵體的熵還在下降，有序度還在上升，像漆黑海面上升起的磷火，這就是意義，最高層的意義，比樂趣的意義層次要高。」——《三體：死神永生》