優(yōu)雅整潔的 Java 代碼命名技巧，風(fēng)之極·凈化
合格的程序員不僅僅是讓代碼跑起來，而是要做到代碼整潔，只滿足為了能讓編譯器通過編譯，機(jī)器能跑就行而寫代碼的程序會(huì)算不上開發(fā)者，碼農(nóng)都不算。
好的命名能體現(xiàn)出代碼的特征，含義或者是用途，讓閱讀者可以根據(jù)名稱的含義快速厘清程序的脈絡(luò)。
本篇分享如下代碼命名套路來提高我們代碼命名：
- 勿模糊，準(zhǔn)確達(dá)意
- 避免誤導(dǎo)
- 做有意義的區(qū)分
- 結(jié)合上下文簡(jiǎn)化名稱
- 使用可搜索、易讀的名稱
- 包命名規(guī)范
- 類名與方法名規(guī)范
混亂的代價(jià)
我相信每個(gè)程序員都被某些人的垃圾代碼惡心過，導(dǎo)致開發(fā)進(jìn)度被嚴(yán)重延緩、性能差勁、bug 多。
每次新增和修改代碼如履薄冰，我們只有對(duì)那堆腐朽的代碼了然于胸才敢修改。
隨著時(shí)間推移，團(tuán)隊(duì)生產(chǎn)力下降，所有人都抵觸這個(gè)項(xiàng)目，對(duì)其束手無策。
新手不熟悉原來的場(chǎng)景和設(shè)計(jì)，不知道如何修改才符合實(shí)際意圖，導(dǎo)致更容易出現(xiàn)混亂。
最后，開發(fā)團(tuán)隊(duì)產(chǎn)生了抵觸心理并造反了，再也無法忍受在這個(gè)垃圾代碼基礎(chǔ)上做開發(fā)，而管理層不愿意投入資源重新設(shè)計(jì)。
一個(gè)優(yōu)秀的開發(fā)者應(yīng)該時(shí)刻保持代碼整潔，無關(guān) deadline。
為什么會(huì)寫出垃圾代碼呢?
有的人可能會(huì)說，需求變化違背了最初的設(shè)計(jì)、排期太緊沒法干好......
其實(shí)，這是一種不專業(yè)的托詞。
推進(jìn)進(jìn)度是產(chǎn)品經(jīng)理他們?cè)摳傻模m然癡迷于進(jìn)度，但是多數(shù)產(chǎn)品經(jīng)理也會(huì)期望有良好的可拓展代碼以便應(yīng)對(duì)市場(chǎng)變換莫測(cè)的需求。
連海誓山盟的愛情都會(huì)變，又如何做到需求不會(huì)改變呢?
所以我們比他們更加重視代碼質(zhì)量，才能應(yīng)對(duì)變化的需求。
保護(hù)代碼持續(xù)整潔優(yōu)雅是每個(gè)優(yōu)秀開發(fā)者都應(yīng)該遵守的原則。
混亂的代碼只會(huì)拖慢未來的開發(fā)進(jìn)度，唯一加快進(jìn)度的方法：始終盡可能保持代碼優(yōu)雅整潔。
好比醫(yī)生在做手術(shù)之前要先消毒，你說消毒太耗時(shí)間了，直接拿刀子整吧。
作為專業(yè)的醫(yī)生你會(huì)照做么?
作為專業(yè)的程序員，我們要了解代碼變壞的風(fēng)險(xiǎn)并堅(jiān)持保持代碼質(zhì)量。
什么是整潔代碼
代碼質(zhì)量評(píng)判需要綜合各種因素得到的，我們并不能從單一的維度去評(píng)判。
比如代碼可讀性好，但是空間與時(shí)間復(fù)雜度高，這并不能算得上是好代碼。
好的代碼應(yīng)該具備：易拓展和維護(hù)、簡(jiǎn)潔(只做好一件事)、可復(fù)用性強(qiáng)(沒有重復(fù)代碼)、能快速寫出單元測(cè)試。可讀性強(qiáng)、沒有副作用(做了名稱以外的工作)。
易拓展和維護(hù)
在不破壞原來的代碼設(shè)計(jì)下，可以簡(jiǎn)單快速的修改和添加代碼實(shí)現(xiàn)功能拓展。
簡(jiǎn)單地說就是預(yù)留了拓展點(diǎn)，將新代碼放在設(shè)計(jì)的可拓展點(diǎn)，不會(huì)因?yàn)樾略鲆粋€(gè)功能而改動(dòng)大量原始代碼。
對(duì)修改關(guān)閉，對(duì)拓展開放，開閉原則。
對(duì)于開發(fā)而言，我們維護(hù)舊代碼的時(shí)間超過新項(xiàng)目新代碼的時(shí)間。
代碼的可維護(hù)性就變得很重要，也就是說代碼分層清晰、模塊劃分精當(dāng)，滿足高內(nèi)聚低耦合、抽象出合理的接口，面向接口編程就意味著有較好的可維護(hù)性。
同樣的代碼，熟悉他的資深工程師會(huì)覺得很容易維護(hù)，而新人因?yàn)椴皇煜ごa，不懂設(shè)計(jì)模式而無法理解。
所以，易拓展具有主觀性，我們需要提高基礎(chǔ)技能才有資格說代碼是否易拓展和維護(hù)。
只做好一件事
單一職責(zé)：每個(gè)函數(shù)、每個(gè)類、每個(gè)模塊只專注于一件事。
不要設(shè)計(jì)大而全的類或者函數(shù)，我們需要將他們拆分成更細(xì)粒度功能更加單一的類。
它不會(huì)隱藏設(shè)計(jì)者的意圖，干凈利落的抽象和直截了當(dāng)?shù)目刂普Z句。
我們應(yīng)該讓每個(gè)函數(shù)每行代碼簡(jiǎn)單、邏輯清晰。這樣的話，類依賴和被依賴的類也會(huì)變少，減少耦合度。
需要注意的是，也不能拆分太細(xì)，否則就會(huì)破壞內(nèi)聚性。
高手，就是用最簡(jiǎn)單的方法去解決復(fù)雜問題。
沒有重復(fù)代碼
在開發(fā)過程中，我們應(yīng)該盡可能抽象出「變與不變」，復(fù)用已經(jīng)存在的代碼，不要寫重復(fù)的代碼。
比如運(yùn)用「封裝、繼承、抽象、多態(tài)」特性，代碼封裝成模塊，隱藏變化的細(xì)節(jié)，暴露不變的接口。
把業(yè)務(wù)與非業(yè)務(wù)的代碼邏輯分析，抽象成通用的框架、工具類等。
比如應(yīng)用模板方法設(shè)計(jì)模式將不變的算法邏輯框架定義出來，把變化的點(diǎn)延遲到子類重寫。
能快速寫成單元測(cè)試
代碼的可測(cè)試性差，比較難寫單元測(cè)試，那基本上就能說明代碼設(shè)計(jì)得有問題。
試想下，如果一個(gè)類大而全，有一個(gè)方法依賴了十幾個(gè)外部對(duì)象才能完成工作，耦合嚴(yán)重。
當(dāng)你在編寫單元測(cè)試的時(shí)候，需要 mock 十幾個(gè)依賴對(duì)象和數(shù)據(jù)。
那說明這個(gè)代碼糟透了，需要合理拆分和設(shè)計(jì)。
可讀性強(qiáng)
軟件設(shè)計(jì)大師 Martin Fowler 說過：「Any fool can write code that a computer can understand. Good programmers write code that humans can understand.」
翻譯成中文就是："任何二貨都會(huì)編寫計(jì)算機(jī)能跑的代碼。優(yōu)秀的程序員能夠編寫人能夠理解的代碼。”
而可讀性就會(huì)涉及到編碼規(guī)范、命名、注釋、函數(shù)職責(zé)是否單一、長(zhǎng)度是否精簡(jiǎn)。
有數(shù)據(jù)顯示讀代碼的時(shí)間與寫代碼的時(shí)間比例超過 10：1，并且編寫當(dāng)前代碼的難度，取決于讀周邊代碼的難度。
所以我認(rèn)為可讀性強(qiáng)是最重要的一點(diǎn)。
高質(zhì)量命名套路
開發(fā)過程后命名隨處可見，我們給變量、方法、參數(shù)、類、包命名。
而命名的好壞會(huì)影響我們的可讀性，我們不妨從命名作為切入口來寫好代碼。
勿模糊，準(zhǔn)確達(dá)意
在開發(fā)過程中，一旦發(fā)現(xiàn)更好的名稱，就換掉舊的。
一個(gè)變量、方法、或者類的名稱應(yīng)該展示出它該有的功能。根據(jù)名字我們能知道它能做什么事情，如何使用。
如果一個(gè)名稱需要大量注釋來補(bǔ)充避免使用者跳坑，那就是糟糕的名字。
- 變量名體現(xiàn)出該字段作用，比如 LocalDate now = LocaDate.now(); now 標(biāo)識(shí)當(dāng)前時(shí)間。
- 防止出現(xiàn)讓人模糊無法理解，必須還要依據(jù)大量上下文才能理解的代碼。
- 不要使用魔術(shù)。
反例 1 ：使用魔數(shù)
- // 從數(shù)據(jù)庫(kù)獲取列表
- List<String> buyerList = dao.getList();
- buyerList.forEach(x -> {
- for (int i = 1; i <= 5; i++) {
- processedBuyerList.add(String.format("%s,%s", i, x));
- }
- });
你會(huì)疑問，為啥索引是從 1 開始?為啥 <= 5。除此之外， i 與 1 極其相似，難以區(qū)分。
正確的方式應(yīng)該使用實(shí)際含義的名字讓人理解這么寫的目的，否則維護(hù)的人將痛苦不堪。
反例 2：使用生僻字，又臭又長(zhǎng)
UltimateAssociatedSubjectRunBatchServiceImpl，當(dāng)我們看到這樣的類名，是不是不知道怎么讀，也不知道如何搜索和定位，更不知道到底表達(dá)的意思是什么，可能命這個(gè)名字的人還以為準(zhǔn)確表達(dá)，其實(shí)是“王大媽的裹腳布，又臭又長(zhǎng)”。
原本的業(yè)務(wù)含義是：執(zhí)行關(guān)聯(lián)主體任務(wù)相關(guān)業(yè)務(wù)類。
鑒于此，我們第一步要避免使用生僻字，可以命名為L(zhǎng)inkSubjectServiceImpl ，清晰簡(jiǎn)單的表達(dá)出關(guān)聯(lián)主體的業(yè)務(wù)邏輯都在該類。
不要誤導(dǎo)
盡量不要使用不同之處較小的名稱，這樣讓他人無法一眼區(qū)分兩個(gè)名稱是啥意思。
例如：函數(shù) deleteIndex 和函數(shù)deleteIndexEx，這兩個(gè)函數(shù)名區(qū)別很小了，加之函數(shù) deleteIndexEx后面Ex還是縮寫，也不知道是什么意思，所以他人只能去看函數(shù)內(nèi)容才能明白兩者的區(qū)別。
- XYZStringHandler與 XYZStringStorage。
- UserController與 UserInfoController。
讓人抓狂，他們到底是一個(gè)東西還是不同的?差別在哪?沒有兩年腦血栓寫不出這樣的。
反例 3：名不副實(shí)
下面是一個(gè)生成文件并提供下載功能的接口。
- public void downloadExcel(HttpServletResponse response) {
- List<File> files = listFile();
- String fileName = System.currentTimeMillis() + ".zip";
- DownloadZip.downLoadFiles(files, filePath);
- DownloadZip.fileDownload(response, filePath, fileName);
- }
我們會(huì)疑惑，downLoadFiles 與 fileDownload 到底有啥區(qū)別?為啥要調(diào)用兩次。
這種真的是十年腦血栓才寫得出來。
downLoadFiles 的功能是創(chuàng)建將 files 打包成 zip 文件，而 fileDownload則是把指定的文件輸出給瀏覽器下載。
所以 downLoadFiles 應(yīng)該命名為 createZipFile用于合理區(qū)分避免誤人子弟。
做有意義的區(qū)分
- getActiveOrder();
- getActiveOrderInfo();
- getActiveOrderData();
- getActiveOrders();
上面都是廢話命名，別人你怎么知道到底該調(diào)用那個(gè)方法?
哪個(gè)表示訂單明細(xì)?還是歷史訂單，還是全部訂單查詢，廢話是另一種沒有意義的區(qū)分。
名稱不同，意思卻無差別。
Order、OrderInfo、OrderData，他們名稱相同 ，意思卻無差別，屬于毫無意義的廢話。如果缺少明確約定，變量moneyAmount就與money沒區(qū)別。
Variable一詞永遠(yuǎn)不應(yīng)當(dāng)出現(xiàn)在變量名中。Table一詞永遠(yuǎn)不應(yīng)當(dāng)出現(xiàn)在表名中。
結(jié)合上下文簡(jiǎn)化名稱
- public class Order {
- private String orderNum;
- private String orderCreateTime;
- //...
- }
比如 Order類，在該上下文中，沒必要給每個(gè)成員變量重復(fù)添加 order 這個(gè)前綴單詞，直接命名為 createTime、num。
因?yàn)槲覀兛梢越柚?Order 這個(gè)上下文來獲取信息。
- Order order = new Order();
- order.getCreateTime();
名稱易讀、可搜索
可讀指的是不要使用一些生僻字，難以發(fā)音的單詞。
可搜索是便于利用 IED 的自動(dòng)補(bǔ)全和搜索功能，能根據(jù)我們的命名規(guī)范快速定位想要找的類或者方法等。
可讀
名稱讀不出來，在討論的時(shí)候就好像是一個(gè)沙雕。
哎，那個(gè)「treeNewBeeAxibaKula」類是什么作用?
聽到這樣的名字尷尬癌都犯了。
使用一些生僻字，猶如「王大媽的裹腳布，又長(zhǎng)又臭」，沒有兩年腦血栓寫不出這樣的垃圾代碼。
可搜索
IED 很智能，當(dāng)我們輸入 「Hash」的時(shí)候，會(huì)列舉出所有 Hash 相關(guān)的類。
命名的時(shí)候最好符合項(xiàng)目命名習(xí)慣，列表數(shù)據(jù)查詢大家使用 listXXX，你就不要用 queryXXX，統(tǒng)一命名規(guī)范，很重要。
包命名
包名統(tǒng)一使用小寫，點(diǎn)分隔符之間有且僅有一個(gè)自然語義的英文單詞或者多個(gè)單詞自然連接到一塊(如 springframework，deepspace 不需要使用任何分割)。
包名的構(gòu)成可以分為以下幾四部分【前綴】 【發(fā)起者名】【項(xiàng)目名】【模塊名】。
以下表格授權(quán)于「Java 填坑筆記」
常見的前綴可以分為以下幾種：
類名
類名使用大駝峰命名形式，應(yīng)該使用名詞或者名詞短語，比如：Customer、Account。
避免使用 Manager、Processor 等動(dòng)詞。
接口名除了用名詞和名詞短語以外，還可以使用形容詞或形容詞短語，如 Cloneable，Callable 等，表示實(shí)現(xiàn)該接口的類有某種功能或能力。
方法名
方法命名一般為動(dòng)詞或動(dòng)詞短語，與參數(shù)或參數(shù)名共同組成動(dòng)賓短語，即動(dòng)詞 + 名詞。一個(gè)好的函數(shù)名一般能通過名字直接獲知該函數(shù)實(shí)現(xiàn)什么樣的功能。
布爾返回值的方法
注：Prefix-前綴，Suffix-后綴，Alone-單獨(dú)使用
按需執(zhí)行的方法
用來檢查的方法
異步相關(guān)方法
回調(diào)方法
操作對(duì)象生命周期的方法
4.7 與集合操作相關(guān)的方法
與數(shù)據(jù)相關(guān)的方法
成對(duì)出現(xiàn)的動(dòng)詞
| 單詞 | 意義 |
| get獲取 | set 設(shè)置 |
| add 增加 | remove 刪除 |
| create 創(chuàng)建 | destory 移除 |
| start 啟動(dòng) | stop 停止 |
| open 打開 | close 關(guān)閉 |
| read 讀取 | write 寫入 |
| load 載入 | save 保存 |
| create 創(chuàng)建 | destroy 銷毀 |
| begin 開始 | end 結(jié)束 |
| backup 備份 | restore 恢復(fù) |
| import 導(dǎo)入 | export 導(dǎo)出 |
| split 分割 | merge 合并 |
| inject 注入 | extract 提取 |
| attach 附著 | detach 脫離 |
| bind 綁定 | separate 分離 |
| view 查看 | browse 瀏覽 |
| edit 編輯 | modify 修改 |
| select 選取 | mark 標(biāo)記 |
| copy 復(fù)制 | paste 粘貼 |
| undo 撤銷 | redo 重做 |
| insert 插入 | delete 移除 |
| add 加入 | append 添加 |
| clean 清理 | clear 清除 |
| index 索引 | sort 排序 |
| find 查找 | search 搜索 |
| increase 增加 | decrease 減少 |
| play 播放 | pause 暫停 |
| launch 啟動(dòng) | run 運(yùn)行 |
| compile 編譯 | execute 執(zhí)行 |
| debug 調(diào)試 | trace 跟蹤 |
| observe 觀察 | listen 監(jiān)聽 |
| build 構(gòu)建 | publish 發(fā)布 |
| input 輸入 | output 輸出 |
| encode 編碼 | decode 解碼 |
| encrypt 加密 | decrypt 解密 |
| compress 壓縮 | decompress 解壓縮 |
| pack 打包 | unpack 解包 |
| parse 解析 | emit 生成 |
| connect 連接 | disconnect 斷開 |
| send 發(fā)送 | receive 接收 |
| download 下載 | upload 上傳 |
| refresh 刷新 | synchronize 同步 |
| update 更新 | revert 復(fù)原 |
| lock 鎖定 | unlock 解鎖 |
| check out 簽出 | check in 簽入 |
| submit 提交 | commit 交付 |
| push 推 | pull 拉 |
| expand 展開 | collapse 折疊 |
| begin 起始 | end 結(jié)束 |
| start 開始 | finish 完成 |
| enter 進(jìn)入 | exit 退出 |
| abort 放棄 | quit 離開 |
| obsolete 廢棄 | depreciate 廢舊 |
| collect 收集 | aggregate 聚集 |
總結(jié)
命名目的都是為了讓代碼和工程師進(jìn)行對(duì)話，增強(qiáng)代碼的可讀性，可維護(hù)性。優(yōu)秀的代碼往往能夠見名知意。
本文轉(zhuǎn)載自微信公眾號(hào)「碼哥字節(jié)」
