代碼混亂的常見問題

很多時候我們項目迭代到后期，項目會變得很混亂，往往只有少數人能知道某段代碼是干嘛的和該如何去改，或者是干脆誰都不知道，只能靠通過注釋去猜測這段代碼可能的作用。原因有可能是因為團隊內部的人事變動，導致原先寫這段代碼的人不再管理這段代碼了，并且代碼寫的實在是屎沒人捋的清。往往我們稱這類代碼為“祖傳代碼”，就像祖宗傳下來的代碼一樣，沒人懂沒人敢動。祖傳代碼一多，這個項目就變成了屎一樣，開發人員在這基礎上迭代就如同屎海翻騰，惡心別人也惡心自己。這是一個很可怕的惡性循環，我們如何去避免這種事情發生呢？先讓我們分析下這類代碼的通病

代碼又臭又長

我見過最長的方法是5000多行，那段代碼沒人敢動，只敢往下加 if else，每次需要改這段代碼的開發都戰戰兢兢，生怕出現什么莫名其妙的bug。java 可是一門面向對象的語言，一個方法里面有5000多行可以說是很可惡的事情了。我想一開始代碼長度可能沒這么夸張，是什么導致這種結果的？一個是當初寫這段代碼的人本身寫的是直來直去的方法，一堆if else ；后面迭代的開發，面對這么長的代碼瞬間失去了從頭讀到尾的耐心，直接繼續在后面加 if else 迭代，最后這個方法就變成了一個縫合怪一樣的玩意。

好的 sql 可以很大程度上簡化代碼的復雜程度，但是太過復雜sql 本身就會給后來的開發人員造成閱讀困難，結果又是變成一條無人敢動的祖傳代碼，我想這應該是不少公司極度抵制存儲過程的原因之一。當然不少銀行應用開發還是大量使用存儲過程，存儲過程有用武之地的，但是一個又臭又長的存儲過程就等著變成祖傳代碼吧。當年我見到一個60多個join的sql，看到第一眼就驚為天人從此難以忘懷，當然那段sql也成了沒人敢去動的代碼了。

代碼邏輯不明

代碼邏輯不明所以是我們開發很容易去犯的毛病，是一個不致命卻煩人的毛病。在代碼上的體現是，邏輯判斷寫的比較反人類各種雙重否定是肯定，不把你繞暈不罷休。或者是寫起代碼來東一榔頭西一棒槌，讓人不知道你想干嘛。導致這個的原因有可能是開發人員在需求理解上出現偏差，做到后面發現不對勁，再回去改又不大可能了，只能硬著頭皮往下寫，結果就是代碼彎彎繞繞；還有很重要的鍋是在產品經理，任意變更需求，想一出是一出，開發人員無奈只能跟著想一出寫一出。還用可能是開發人員方法或者類命名太藝術了，什么四川方言拼音這種沒有十年腦血栓想不出的命名咱就不說了。就說那種國產凌凌漆式的無厘頭命名——這看上去是個刮胡刀實際上是個吹風機，就這種不知道讓人說什么好。

規劃代碼的核心思想

吐槽了一堆代碼規范問題，接下來我們說說如何去規范我們的代碼以及如何做到就算開發人員更換了，或者項目轉手給他人了，仍然可以讓后面的開發可以無礙的去閱讀代碼修改代碼。當然各個公司/團隊都有自己的一套代碼規范，比如項目的結構、代碼命名風格、代碼格式等等。不同團隊有不同的風格，但核心思想是大同小異的。接下來我就我個人的開發經驗來分享一下一些代碼規范的思想。

花葉論

就我個人而言，這個理解是我代碼規范中最淺顯也是最核心的思想，只要稍微動動腦子就能想出這個思路出來。或許我們做業務開發的時候，大部分都在寫crud，感覺似乎這部分代碼沒什么規范好說的，其實不然。對一段業務代碼而言，我們可以將其分為四類：

數據校驗

業務邏輯

數據轉換

數據庫交互（查詢與持久化）

大部分時候我們最關心的是邏輯判斷相關的代碼，其次是數據庫交互，對于遠程調用的方法，我們就視其為一個普通的方法以簡化模型，方法調用算業務邏輯部分的代碼，對于讀代碼的人而言基本上不關心數據校驗和數據的轉換（DTO轉VO等）。因此，代碼應該分出一個主次，應該盡量把主邏輯給凸顯出來，最好一眼看去就能讓人明白這個方法或者這個類干了啥，步驟是什么樣的。對于那些不重要但必要的代碼我稱其為葉，對于那些主要的代碼我稱其為花。葉是為了襯托花的，因此我們應該將那些葉子代碼精簡或者隱藏起來。

隱藏葉子代碼，突出主干邏輯的一些手法

1）Converter（轉換器）

大部分時候我們使用 bean 拷貝使用的是BeanUtils這個類來完成，然而一些稍微復雜的實體轉換，這個類就無法勝任了，這個時候我們只能手動的 get set ,往往就是這些get set 方法掩蓋了主干邏輯，讓代碼結構不清晰。因此我建議在你的業務邏輯代碼中引入1）Converter這個角色來專門負責數據的傳遞與轉換。

2）manager 層

無論我們使用的持久層框架是哪一種，jpa 或者 mybatis 我覺得我們都應該對持久層的部分方法進行簡單封裝一下，這也是阿里規范里面提倡的。這樣做好處是明顯的，我們做一個查詢時往往要 set 一些查詢條件或者對查詢結果進行一些簡單的判斷，往往這類操作在業務代碼可能有比較高的重復性。如果把這些代碼放到業務邏輯代碼里面，少量還好，多了的話就顯得很臃腫了。如果把這種代碼移到manager層里面去，不僅主業務邏輯代碼不會被干擾，還能提高一定的代碼復用率。

3）方法簡單封裝

假設我們一個方法要完成一段邏輯要分成三大步，而每一個步驟又分成幾個小步驟，那我們就可以將這個方法拆分成三個方法，然后在這三個方法里面完成各自的步驟。這手法是很簡單的，想必大家都能想到，但是我這里要介紹的是簡化復雜方法封裝的神器——函數式編程，我這里指的函數式編程不僅僅是 stream 流和 lambda 表達式的使用。函數式編程封裝適用的場景是：整個流程比較固定，但是某幾個步驟變化是不確定的。我們可以去看看java.util.function這個包的源碼，你會發現這個包下面全是接口，這些接口被稱為函數式接口。這些函數式接口總體上分為四類：

Function 類型：傳入一個bean 返回另外一個bean

Consumer 類型：傳入一個bean 無返回值

Predicate 類型：傳入一個bean 返回布爾值

Supplier 類型：沒有入參，有出參

以 Consumer 的使用為例：

public User getUser(Consumer consumer){
User user=new User();
consumer.accept(user);
user=userMapper.getUser(user);
return user;
}

public void doSomething1(){
User user=getUser(user->{user.setId(1L)});
}

public void doSomething2(){
User user=getUser(user->{user.setName("xxx")});
}

函數式編程的想象空間很大，使用的得當必定會簡化你的代碼，提高代碼復用率。但是在多線程中使用函數時要留意數據的可見性問題。

日志和注釋的一些個人經驗

1）日志

首先我們要明白日志是給人看的，你加這段日志時要考慮清楚，有沒有人會去查這段日志，這段日志有沒有用。然后我們查閱日志的時候，一般會通過關鍵詞去搜索；因此我們打的日志一定要有關鍵詞，而且這個關鍵詞不要和其他日志重復，不要過長，便于搜索才是王道。大部分情況我們查看日志都是為了追溯bug，那么一個基本原則就是能通過日志分析出業務邏輯或者流程的走向，對此我建議打日志的地方：

數據更新：我們有必要知道寫庫的數據是不是正確的數據；

條件分支：便于我們分析業務走的哪一條邏輯；

批量寫庫：打上數據量大小的日志，便于我們分析性能瓶頸。

并不是所有的這些地方都應該打上日志，有的時候我們可能只需要通過一兩條日志就能分析出整個流程的問題點在哪，這個時候其他的日志就顯得多余了。還有我們打完日志之后應該在本地環境追溯一下，看看這些日志自己是否能讀懂，是否有必要，是否少了重要參數。

2）注釋

最基本的兩個注釋——類注釋，方法注釋相關規范阿里開發手冊上就有，我這里就不復述了，我分享下我寫注釋的個人習慣。方法注釋上除了基本的注釋，我還會將產品需求的原文貼重要的部分上去再寫上日期，這樣做的好處是讓別人明白產品需求要求干啥這個方法該干啥，而且產品經理偷偷改需求你還能有追查的根據，有個小本本偷偷記錄他的罪行。

代碼注釋我分享一個我偷師來的小技巧：

pulic void test(){
/** 1. 從excel 獲取 vo*/
Workbook workBook = getWorkBook(wookbookStream);
//獲取成員信息
Sheet userSheet = workBook.getSheetAt(3);
Map userVOMap = getUserForExcel(file, userSheet);
// 獲取項目vo
Sheet projectSheet = workBook.getSheetAt(0);
ProjectVO projectVO = getProjectForExcel(file, isInsert, userVOMap);
// 獲取任務vo
Sheet taskSheet = workBook.getSheetAt(1);
Map taskVOMap = getTaskListForExcel(file, taskSheet, userVOMap);
/** 2. 插入數據 */
if (isInsert.get()){
......
}
/** 3.寫入異常信息 */
if (!isInsert.get()) {
.....
}
}

如你所見，對于主干的步驟 我用/** 1. *//** 2. */javadoc的注釋來標注了，而普通的注釋我用//標注，因為idea 在純黑主題下會給/**這樣的注釋配上綠色，會比較顯眼。我通過這種方式來強調我代碼哪些是花，哪些是葉子。當然這種方式實際上是不大符合代碼規范的，小伙伴們理性取舍，這種手法未必好。

六大基本原則

對于面向對象的的語言，六大基本是很重要的開發準則，但似乎大部分人在寫代碼的時候都不大在意這個，這也是導致一個方法變得又臭又長的一個重要原因之一。對于類的復雜度我們應該遵循單一職責原則——一個類或者方法承擔的職責越多，它被復用的可能性就越小，重構或者修改起來就會變得困難重重，我們應該盡量讓一個方法只去做一件事情。

對于許多代碼我們只要通過一些簡單的手法就能很好的提高其擴展性，比如通過接口去實現類與類之間的協作就能提前解決掉許多未知隱患，而且運用得當的情況下還能滿足開閉原則與里氏替換原則，其實service層的設計就有那么點味道了，而且spring的特性也支持接口注入List和map，然而許多開發多年的同學都不知道這個特性，這個特性在許多場景下可以提高代碼的擴展性，眾所周知，map可以減少代碼的 if else 分支。

方法命名 ‘潛規則’

很多時候，好的方法命名本身就是對代碼的一種注釋，我這里好的方法命名是指大家約定俗成的命名規則。如果你多留心各個開源框架的代碼都會發現一些特定的命名規則。阿里開發手冊里面也列舉不少命名前綴與后綴的規范，其實各個團隊可以根據自己的實際情況規定一些命名規則，降低團隊內部的代碼閱讀的成本。

介紹過部分命名規則，感興趣的小伙伴可以去看看。

代碼提交及版本控制

正確代碼提交日志格式可以幫助開發人員及時的縷清代碼的修改歷史，從而快速的定位問題。以git為例，我們大部分人提交日志就是幾個字而已，當然你能夠通過日志去定位到自己的修改歷史的話，這樣做也沒什么大問題，但是對于團隊而言，你的修改日志要讓別人能看懂就得按一定的格式來寫了。Git Commit message的 Angular規范中定義的 commit message 格式有3個內容：

Header Header部分有3個字段：type(必需), scope(可選), subject(必需)

Body 部分是對本次 commit 的詳細描述，可以分成多行。

Footer不常用，可為空 包括不兼容變動、關閉issue。

這里由于篇幅問題不細說，感興趣的小伙伴可以百度查查資料。我們團隊不一定要按照這么嚴格的規則來，但是可以制定一個類似的規范來管理提交日志。

對于團隊而言，gitflow 是一個很不錯的開發流程。可以很大程度上管理好我們的分支代碼，避免團隊的人由于誤操作而導致某個重要分支出現問題。下面貼出gitflow 流程圖，對于其具體內容同樣不會介紹太多，感興趣的小伙伴去百度吧

幫助代碼規范的工具

本節主要介紹提高代碼質量的idea插件和框架，當然大名鼎鼎的 阿里代碼規范插件咱就不介紹了，想必大家多少了解。不過本人感覺這個插件并不適合一些團隊，一是感覺這個規范太過嚴格，對開發人員素質要求太高，二是有的團隊有自己的規范規則，而且有可能和阿里規范沖突，不適用于這個插件。下面介紹的插件可能不適合一些小伙伴。我列舉出來大家自己尋思吧。

mapstruct

對于我而言是很喜歡這個東西的，這個框架解決的問題其實就是我上文提到的花葉論中的 “數據轉換” 的問題。其實不少公司也有類似的概念——定義一個工具類作用是將 DO轉VO 或者 VO轉DTO等，一般這類類都是以converter結尾。而mapstruct這個框架通過編譯器生成字節碼來自動的生成bean的轉換類。我們想將一個bean的數據賦值給另外一個bean只需要去定義接口即可。這樣既減輕了開發人員的工作量還將無意義的get和set方法從邏輯代碼塊中剔除出去。這個框架的缺點是字節碼緩存問題，用過類似自動生成字節碼工具的小伙伴應該知道——mapstruct 是根據接口去自動生成類的，當我們更新了接口的時候，這個類有可能沒重新生成，當然這只有用idea調試的時候才會有的問題，所以也不必太擔心。

checkStyle

idea checkStyle 插件可以通過自定義配置文件來統一團隊的代碼風格和代碼規范，降低團隊的交流成本，一般配合 save actions Reborn 使用更佳。關于checkStyle的配置文件網上也不少，這里也不貼出來占篇幅了。

git flow

前文提到過git flow 給團隊帶來的好處，idea也有對應的插件——git Flow Integration，可以通過這個插件來規范我們的流程：

開發新功能選擇 start Feature 拉取分支，修復bug 選擇 Start Bugfix 拉取分支，等等。此外還有 push on finish等功能，小伙伴如果感興趣可以百度。

Git Commit Template

這個主要是用來規范git commit 的一個idea插件小工具了，github上也有類似的開源插件。團隊內部也可以自己開發一個類似插件，比較簡單，成本也不高。

代碼規范的一些個人看法就聊到這了，喜歡的小伙伴可以分享一下哦。

CloudLinux將在本季度推出AlmaLinux取代CentOS