Java程式碼規範和一些常見問題

小雷FansUnion發表於2016-04-19
Java
   本文中的程式碼規範，是Java標準程式碼規範中的一小部分，在我看來，是最重要的一部分。

   理想目標：不需要寫註釋，不需要和別人介紹，別人就知道你的專案大致是做什麼的，每個類大概實現了什麼功能。

一.目的
     一致性、快速閱讀和理解
    後期維護、提高工作效率
    團隊協作

二.程式碼命名一般原則

在JAVA程式碼中，所有的程式碼命名的總原則是：

    1. 用標準的儘可能無歧義的全英文單詞命名的方式，準確地描述變數、屬性、類等。
      如：使用firstName, grandTotal等命名，就比x1,y1,fn等更容易讓人理解其含義，儘管它們的長度要大一些。
      
    2. 採用一些更加準確的術語來命名。例如，如果我們的使用者稱他們的clients為customers，那麼我們就應該採用customer來命名，而不是採用client來命名。這是一些細微的地方，但也希望能注意。
    3. 採用大小寫混合的方式來命名，以便命名有很好的可讀性。在JAVA程式碼中，將採用如下原則：類或介面命名中每個單詞的首字母均大寫，而單詞的剩餘部分均小寫。其它像變數、成員方法、屬性等除第一個單詞全部小寫以外，其它單詞的首字母均大寫，而單詞的剩餘部分均小寫。
     比如，productDao.
    4. 儘量少用單詞的縮寫形式，但如果一定要用，則必須要選擇大家通用的縮寫方式，並且要在本JAVA原始碼中堅持用它，而不要一會用這種縮寫方式，一會用那種縮寫方式。比如，如果要用“number”的縮寫方式，則可用“no”或“num”兩種縮寫方式，而不要用“nu”這種大家不常用的縮寫方式，並且要保持不變。
    5. 儘量避免太長的命名，一般以少於20個字元為宜。
        一般都不會超過。
    6. 儘量避免使用這樣的命名：兩個或多個命名僅僅是其中的有些字元大小寫不一樣，或者僅僅是其中有些單詞是單複數之區別。例如：persistentObject 與 persistentObjects;  anSqlDatabase 與 anSQLDatabase等。
    7. 儘量避免使用下劃線。
      在JAVA中，一般比較少的採用下劃線的命名方式。
   8.函式用動詞，類名、屬性名等用名詞。
      public class Product{}
       比如，public void add();

三、程式碼註釋使用的一般原則和型別

在JAVA程式碼中，我們經常要使用程式碼註釋的方式來幫助理解程式碼的含義。

程式碼註釋的一般原則主要有以下幾個方面：

1．程式碼中的註釋應該以讓人一目瞭然為目標。

     我們之所以要增加程式碼註釋，其目的就是為了讓編寫程式碼的人、同一專案組的成員或以後的開發人員能很容易的理解其程式碼的意圖。

2．避免使用標語式的、實際毫無用處的程式碼註釋。

3．儘量採用簡潔、易懂的註釋程式碼，而不要長篇大論。

4．註釋哪些部分：類的目的（即類所完成的功能）、設定介面的目的以及應如何被使用、

      成員方法註釋（對於設定與獲取成員方法，在成員變數已有說明的情況下，可以不加註釋；普通成員方法要求說明完成什麼功能，引數含義是什麼？返回什麼？）

    普通成員方法內部註釋（控制結構、程式碼做了些什麼以及為什麼這樣做，處理順序等）

     實參和形參的含義以及其他任何約束或前提條件、欄位或屬性描述。

    而對於區域性變數，如無特別意義的情況下不加註釋。


四、約定由於配置
     只需要看名字，就知道程式碼，大致是做什麼的，不需要任何人任何的解釋說明。

    1.專案名稱：front，backend，mobile
    2.包名稱和結構
      控制層：com.companyName.front.controller
      業務邏輯/服務層: com.companyName.front.service
      資料訪問層/持久層: com.companyName.front.dao
      模型：com.companyName.front.model, domain,bean
      工具類：*.util
      攔截器：*.interceptor
   3.類的名稱 
      模型：Product（標準的無歧義的英文單詞）
      控制器：*Controller，ProductController
      服務：*Service，ProductService
      持久層：*Dao，ProductDao (ProductDAO，ProductMapper)

   4.配置檔案
      Mybatis配置檔案：
            ProductDao.xml （ProductMapper.xml）
            mybatis-config.xml
      Spring配置檔案：
          spring-mvc-servlet.xml
          spring-dataSource.xml
    屬性檔案
         log4j.properties
         redis.properties
         mail.properties
         
              
          
常見問題
        1.函式名稱不能準確地表達函式的作用。
        
          saveSkirt，saveTrouser
2. 名稱用單數，而不是複數。
     
   如果要用複數，所有的都用複數。
3.名字有歧義。
   做的功能是，“使用者意見反饋”，實際命名用的是“投訴”。
   
  

   

4.命名不統一。
   
 5. 名字不恰當。
  5.1 service層的程式碼，強調的是“對外的介面”。
   而insert更側重於資料庫mysql的插入。
   service層用add和save，比insert更恰當。
      
函式程式碼，表達的是增加1條“收藏” ，因此也可以用有“收藏”含義的動詞，比如collect。


5.2withdraw，經常用的含義是“銀行提現、資金提現”，沒有“退貨”的意思。
  


  
  5.3函式想表達的含義是，“構造一個查詢物件”，buildCriteria更準確。
    




    一般的set方法，肯定會有 引數，並且沒有返回值。
   比如：
   public void setTitle(String title){
        this.title = title;
   }

 6. 方法名不簡潔。
    在WithdrawService中的save方法，預設就應該是儲存Withdraw物件。
    同理，ProductService中的save方法，預設就是儲存商品。
    不需要帶上多餘的詞彙。
  
7.作用域過大
   根本不會被外部方法呼叫，卻使用了public。
  
  8.程式碼重複，難以維護
   如果一段程式碼，出現了第2次，那麼出現第3次的可能性高達99%...
   方式一：提取工具方法到工具類
    
   方式二：抽象流程、抽象介面
   方式三：攔截器
   比如：登入攔截、許可權檢查

 值得探討的幾個問題
1.程式碼行數
  
   1個函式寫了100多行。

    Controller層的程式碼，一般都比較簡單，呼叫Service層的介面，包裝下資料，就到頁面展示了。
    如果程式碼過大，應該把“邏輯上一起的，完成某個功能的”程式碼，提取成私有的方法。
    類似：
    


最後的建議：單一職責
    1個類、1個函式、1個變數，只完成1件事。
    如果不能一句話，幾個單詞，描述1個函式，1個變數，通常來說，是沒有想清楚要做的事情。
  
  

相關文章