分析一套源代碼的代碼規範和風格並討論如何改進優化代碼

    在上一篇博客中，已經交代過了，我所選的工程實踐題目是物聯網組網智能分析引擎。而後我分別借用百度、谷歌兩大搜索引擎，而且在GitHub以及碼雲中查找了一番，發現要找到與題目相關聯的代碼還真是有些困難。但我又想到，咱們工程實踐的要求是後端使用Spring Boot，前端使用React或者是Vue框架，那麼我這裏就以一個開源的Spring Boot先後端分離的優質項目，來進行代碼規範和風格的分析。

    問題1

問：結合工程實踐選題相關的一套源代碼，根據其編程語言或項目特色，分析其在源代碼目錄結構、文件名/類名/函數名/變量名等命名、接口定義規範和單元測試組織形式等方面的作法和特色；

答：首先該項目的後端開發使用的是Java語言，雖然這個項目不算一個大項目，由於一個大項目定義是投入使用而且受衆很廣，但項目開發不都是從小作到大的嗎，騰訊帝國也並不是一蹴而就，因此咱們開發項目的時候通常都會遵循一個規範來開發。說到開發規範，很出名的一個就是MVC模式，那麼MVC是什麼？MVC全名是Model View Controller，是模型(model)－視圖(view)－控制器(controller)的縮寫，是一種軟件設計典範，用一種業務邏輯、數據、界面顯示分離的方法組織代碼，將業務邏輯彙集到一個部件裏面，在改進和個性化定製界面及用戶交互的同時，不須要從新編寫業務邏輯。

那麼，來看一下這個源代碼項目的目錄結構如何？

能夠很清晰地看到，這個項目所包含的目錄有實體類bean，控制器controller，異常處理exception，接口mapper以及服務service。雖然與原始的MVC開發規範有所出入，但一接觸到這個項目目錄，就基本上可以分辨出這個目錄中的代碼文件在整個項目中是一個什麼做用的部分。就好比bean中的文件，很容易就可以判斷其定義的是項目中所須要使用到的實體類，那麼再驗證一下：

沒錯，這裏定義了兩個字符串變量，以及自動生成的構造方法和一系列get、set方法，很顯然就是一個普通的實體類。

再來觀察一下文件名/類名：ChatResp，所表達的意思很顯然就是聊天，再結合類中所定義的變量msg——message，以及from——從哪兒來，再聯想到該項目是一我的力資源管理系統，那麼很容易就理解，哦！這是一個定義在線聊天功能的類。

再來看一個文件：ChatController，從文件名中很容易發現，按照規範化的編碼，這個控制器顯然與某個Service和Mapper對應，不過這裏只分析代碼規範，模式問題暫且不談。那麼這個文件的部份內容是：

此次重點觀察一下類中的函數名定義，截圖中總共包含三個函數，分別是：getAllHr()，sendNf()以及getSysMsg()，以初中英語單詞儲備量都可以大概猜出來這幾個函數的主要功能是什麼，無非是，獲得全部的人力資源部的信息、發送某個信息以及得到系統信息。固然，函數具體的做用還要具體狀況具體分析。

同時注意到，函數的命名一般是要小寫字母打頭，然後一個單詞大寫。對於類名來講則是首字母大寫，後一個單詞一樣也大寫。

 

問題2

問：列舉哪些作法符合代碼規範和風格通常要求

答：按照前面分析的結果，該項目在文件命名、變量命名、類名命名等方面是比較符合常規的規範的，對於沒接觸過這個項目的讀者來講可以在很短的時間內讀懂，這也是一個項目維護管理的基本要求。畢竟進了一個大型的公司，公司內部分工明確，一個項目須要不少人來共同完成，若是別人看了好半天，還沒弄懂這傢伙到底在表達什麼，那還怎麼對接？

其次，咱們注意到代碼的目錄結構比較合理清晰，這也是一個大項目開發的必備要素。這樣的觀念在工程實踐的過程當中也應該樹立起來，就是，咱們寫出來的代碼，不是隻給本身看的，還要與小組其餘成員對接。咱們我的所開發的每每是一個總體項目的幾個零碎模塊，就好像拼圖同樣，幾塊的樣子終究不是全貌，只有湊在一塊兒纔會大放異彩。

最後，項目中還體現出一張風格，是每一個Java程序員應該培養的，那就是縮進。縮進的做用，就如同語文中的標點符號，試想一下，去掉標點符號，朱自清的《春》是否是也沒那麼惟美了？看着實在難受。那麼一樣的，在編寫代碼的時候，適當地使用縮進和空行，可以很大程度上提升代碼的可讀性。

 

問題3

問：列舉哪些作法有悖於「代碼的簡潔、清晰、無歧義」的基本原則，及如何進一步優化改進

答：在類、變量的命名中，微人事這個項目作到了簡潔、清晰、無歧義，可是在函數命名上有一些還存在着歧義的表達，就好比我以前列舉的getSysMsg()——獲取系統信息，那麼這裏的系統信息是什麼？在沒看到函數主體內容以前，我可能猜測是前端的表單信息，但實際上這裏獲取的是分頁的一些信息。因此將函數名改正爲getSysMsgByPage()或許要清晰許多。

這裏，一樣暴露出項目的另外一個問題，就是註釋太少！前面說過，代碼並不是寫給本身看的，同事和學習者都須要快速瞭解到這段代碼的具體做用，特別是這個項目在GitHub上的Star已經超過10000的狀況下。在認真閱讀了這段代碼以後，我簡單地給出這樣的註釋：

文字並不算多，但對於閱讀代碼的讀者來講，可以先入爲主地對這段有一個總體認識。

 

問題4

問：總結同類編程語言或項目在代碼規範和風格的通常要求

答：事實上，除了主觀性的命名之外，其餘的規範和風格都很容易可以經過IDE（好比IDEA）來實現統一。

但咱們不能老是依賴着IDE，以致於之後手寫代碼都不會了，因此還須要瞭解一下規範的代碼如何編寫？

主要參考：Google Java編程風格指南  https://google.github.io/styleguide/javaguide.html

 

基本命名規範

包命名規範：包名統一使用小寫，點分隔符之間有且僅有一個天然語義的英語單詞。通常單詞使用單數形式，可是類名若是有複數含義的話，則可使用複數形式。

類，接口命名：類的名字必須由大寫字母開頭而單詞中的其餘字母均爲小寫;若是類名稱由多個單詞組成，則每一個單詞的首字母均應爲大寫例如TestPage;若是類名稱中包含單詞縮寫，則這個所寫詞的每一個字母均應大寫，如：XMLExample，還有一點命名技巧就是因爲類是設計用來表明對象的，因此在命名類時應儘可能選擇名詞。

方法名：方法的名字的第一個單詞應以小寫字母做爲開頭，後面的單詞則用大寫字母開頭。能夠爲動詞或動詞+名詞組合。1. 設置/獲取某個值的Method，應該遵循setV/getV規範；2. 返回長度的Method，應該命名爲length；3. 測試某個布爾值的Method，應該命名爲isV；4. 將對象轉換爲某個特定類型的Mehod應該命名爲toF。好比：getDate(); length(); isReady(); toOracleFormat()。

類名：類名採用大駝峯的命名形式，所謂大駝峯就是首字母大寫，例如UpperCameCase。抽象類命名使用 Abstract 或 Base 開頭；異常類使用 Exception 結尾；測試類命名以測試的類名開始，以 Test 結尾。枚舉類名帶上 Enum 做爲後綴，枚舉成員名稱須要大寫，單詞間用下畫線隔開。

 

變量名：

（1）常量，在 Java 中，常量通常指 final 關鍵字修飾的變量。

一、全局常量和類內常量的命名採用字母所有大寫，單詞之間加下畫線的方式。

所謂全局常量即類的公開靜態屬性，使用 public static final 修飾；類內常量指的是私有靜態屬性，使用 private static final 修飾。

二、局部常量則採用小駝峯的形式。所謂局部常量指的是方法內的常量。

（2）可變變量

可變變量通常經常使用小駝峯的命名形式，如 myName ,小駝峯和大駝峯的區別就是，小駝峯首字母小寫，而大駝峯首字母大寫。不過須要注意的是，針對布爾類型的變量，在命名的時候，不要用 is 作前綴,不然部分框架在解析的時候會引發序列化錯誤。

例如標識是否刪除的成員變量 Boolean isDeleted, 它的 getter 方法也是 isDeleted()，框架在反向解析的時候，會誤認爲對應的屬性名稱爲 deleted，從而引發錯誤。

註釋

在每一個程序的最開始部分，通常都用Javadoc註釋對程序的整體描述以及版權信息，以後在主程序中能夠爲每一個類、接口、方法、字段添加 Javadoc註釋，每一個註釋的開頭部分先用一句話歸納該類、接口、方法、字段所完成的功能，這句話應單獨佔據一行以突出其歸納做用，在這句話後面能夠跟隨更加詳細的描述段落。在描述性段落以後還能夠跟隨一些以Javadoc註釋標籤開頭的特殊段落，例如上面例子中的@auther和@version，這些段落將在生成文檔中以特定方式顯示

縮進與空格

一個縮進的距離等於四個空格的距離，但到底是要使用 Tab 縮進來調距離仍是用四個空格代替一個縮進來調距離，這個貌似存在爭議，有些大佬建議用 Tab 鍵，有些大佬建議用空格。我在《碼出高效Java開發手冊》裏，本書的做者是推薦四個空格縮進，禁止使用Tab鍵。

固然，你在使用IDE的時候，當你換行時，不少編輯器是會幫你自動縮進的，大多數IDE都是默認四個空格來縮進。

不過不少 IDE 工具提供了 Tab 鍵與空格之間的快速轉換設置。例如對於 IDEA 這個工具，要設置 Tab 鍵爲四個空格時，能夠在設置那裏勾選 Use tab character(setting->editor->Code Style->選擇你想編輯的語言)；而在 Eclipse 中，就得勾選 Insert spaces for tabs。

關於空格，我有如下建議：

一、二目、三目運算符的左右兩邊都應該加一個空格。

二、註釋的雙斜線與註釋內容之間有且僅有一個空格。

三、方法參數在定義和傳入參數時，多個參數逗號後邊都應該加空格。

四、若是大括號爲空，則簡潔地寫成{}便可，大括號中間無須換行和加空格。

五、左右小括號與括號內部的相鄰字符之間不要出現空格。

六、左大括號前須要加空格。