用Java開發自己的Kubernetes控制器，想試試嗎？

簡潔清爽的代碼風格應該是大多數工程師所期待的。在工作中筆者常常因為起名字而糾結，誇張點可以說是編程 5 分鐘，命名兩小時！究竟為什麼命名成為了工作中的攔路虎。

每個公司都有不同的標準，目的是為了保持統一，減少溝通成本，提升團隊研發效能。所以本文中是筆者結合阿里巴巴開發規範，以及工作中的見聞針對 Java 領域相關命名進行整理和總結，僅供參考。

一，Java 中的命名規範

好的命名能體現出代碼的特徵，含義或者是用途，讓閱讀者可以根據名稱的含義快速釐清程序的脈絡。不同語言中採用的命名形式大相徑庭，Java 中常用到的命名形式共有三種，既首字母大寫的 UpperCamelCase，首字母小寫的 lowerCamelCase 以及全部大寫的並用下劃線分割單詞的 UPPER_CAMEL_UNSER_SCORE。通常約定，類一般採用大駝峰命名，方法和局部變量使用小駝峰命名，而大寫下劃線命名通常是常量和枚舉中使用。

二，包命名

包名統一使用小寫，點分隔符之間有且僅有一個自然語義的英文單詞或者多個單詞自然連接到一塊（如 springframework，deepspace 不需要使用任何分割）。包名統一使用單數形式，如果類命有複數含義，則可以使用複數形式。

包名的構成可以分為以下幾四部分【前綴】 【發起者名】【項目名】【模塊名】。常見的前綴可以分為以下幾種：

三，類命名

類名使用大駝峰命名形式，類命通常時名詞或名詞短語，接口名除了用名詞和名詞短語以外，還可以使用形容詞或形容詞短語，如 Cloneable，Callable 等，表示實現該接口的類有某種功能或能力。對於測試類則以它要測試的類開頭，以 Test 結尾，如 HashMapTest。

對於一些特殊特有名詞縮寫也可以使用全大寫命名，比如 XMLHttpRequest，不過筆者認為縮寫三個字母以內都大寫，超過三個字母則按照要給單詞算。這個沒有標準如阿里巴巴中 fastjson 用 JSONObject 作為類命，而 google 則使用 JsonObjectRequest 命名，對於這種特殊的縮寫，原則是統一就好。

四，方法

方法命名採用小駝峰的形式，首字小寫，往後的每個單詞首字母都要大寫。和類名不同的是，方法命名一般為動詞或動詞短語，與參數或參數名共同組成動賓短語，即動詞 + 名詞。一個好的函數名一般能通過名字直接獲知該函數實現什麼樣的功能。

4.1 返回真偽值的方法

注：Prefix-前綴，Suffix-後綴，Alone-單獨使用

4.2 用來檢查的方法

4.3 按需求才執行的方法

4.4 異步相關方法

4.5 回調方法

4.6 操作對象生命週期的方法

4.7 與集合操作相關的方法

4.8 與數據相關的方法

4.9 成對出現的動詞

五，變量&常量命名

5.1 變量命名

變量是指在程序運行中可以改變其值的量，包括成員變量和局部變量。變量名由多單詞組成時，第一個單詞的首字母小寫，其後單詞的首字母大寫，俗稱駱駝式命名法（也稱駝峰命名法），如 computedValues，index、變量命名時，儘量簡短且能清楚的表達變量的作用，命名體現具體的業務含義即可。

變量名不應以下劃線或美元符號開頭，儘管這在語法上是允許的。變量名應簡短且富於描述。變量名的選用應該易於記憶，即，能夠指出其用途。儘量避免單個字符的變量名，除非是一次性的臨時變量。pojo 中的布爾變量，都不要加 is(數據庫中的布爾字段全都要加 is_ 前綴)。

5.2 常量命名

常量命名 CONSTANT_CASE，一般採用全部大寫（作為方法參數時除外），單詞間用下劃線分割。那麼什麼是常量呢？

常量是在作用域內保持不變的值，一般使用 final 進行修飾。一般分為三種，全局常量（public static final 修飾），類內常量（private static final 修飾）以及局部常量（方法內，或者參數中的常量），局部常量比較特殊，通常採用小駝峰命名即可。

<code>/**
 * 一個demo
 *
 * @author Jann Lee
 * @date 2019-12-07 00:25
 **/
public class HelloWorld {

    /**
     * 局部常量(正例)
     */
    public static final long USER_MESSAGE_CACHE_EXPIRE_TIME = 3600;

      /**
     * 局部常量(反例，命名不清晰）
     */
    public static final long MESSAGE_CACHE_TIME = 3600;

    /**
     * 全局常量
     */
    private static final String ERROR_MESSAGE = " error message";

    /**
     * 成員變量
     */
    private int currentUserId;

    /**
     * 控制檯打印 {@code message} 信息
     *
     * @param message 消息體，局部常量
     */
    public void sayHello(final String message){
        System.out.println("Hello world!");
    }

}/<code>

常量一般都有自己的業務含義,不要害怕長度過長而進行省略或者縮寫。如，用戶消息緩存過期時間的表示，那種方式更佳清晰，交給你來評判。

通用命名規則#

六，代碼註解

6.1 註解的原則

好的命名增加代碼閱讀性，代碼的命名往往有嚴格的限制。而註解不同，程序員往往可以自由發揮，單並不意味著可以為所欲為之胡作非為。優雅的註解通常要滿足三要素。

1. Nothing is strange 沒有註解的代碼對於閱讀者非常不友好，哪怕代碼寫的在清除，閱讀者至少從心理上會有牴觸，更何況代碼中往往有許多複雜的邏輯，所以一定要寫註解，不僅要記錄代碼的邏輯，還有說清楚修改的邏輯。
2. Less is more 從代碼維護角度來講，代碼中的註解一定是精華中的精華。合理清晰的命名能讓代碼易於理解，對於邏輯簡單且命名規範，能夠清楚表達代碼功能的代碼不需要註解。濫用註解會增加額外的負擔，更何況大部分都是廢話。

<code>// 根據id獲取信息【廢話註解】
getMessageById(id)/<code>

6.2 註解格式

註解大體上可以分為兩種，一種是 javadoc 註解，另一種是簡單註解。javadoc 註解可以生成 JavaAPI 為外部用戶提供有效的支持 javadoc 註解通常在使用 IDEA，或者 Eclipse 等開發工具時都可以自動生成，也支持自定義的註解模板，僅需要對對應的字段進行解釋。參與同一項目開發的同學，儘量設置成相同的註解模板。

a. 包註解

包註解在工作中往往比較特殊，通過包註解可以快速知悉當前包下代碼是用來實現哪些功能，強烈建議工作中加上，尤其是對於一些比較複雜的包，包註解一般在包的根目錄下，名稱統一為 package-info.java。

<code>/**
 * 落地也質量檢測
 * 1. 用來解決什麼問題
 * 對廣告主投放的廣告落地頁進行性能檢測，模擬不同的系統，如Android，IOS等; 模擬不同的網絡：2G，3G，4G，wifi等
 *
 * 2. 如何實現
 * 基於chrome瀏覽器，用chromedriver驅動瀏覽器，設置對應的網絡，OS參數，獲取到瀏覽器返回結果。
 *
 * 注意：網絡環境配置信息{@link cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常規速度，可以根據實際情況進行調整
 *
 * @author cruder
 * @time 2019/12/7 20:3 下午
 */
package cn.mycookies.landingpagecheck;/<code>

b. 類注接

javadoc 註解中，每個類都必須有註解。

<code>/**
* Copyright (C), 2019-2020, Jann  balabala...
*
* 類的介紹：這是一個用來做什麼事情的類，有哪些功能，用到的技術.....
*
* @author   類創建者姓名 保持對齊
* @date     創建日期 保持對齊
* @version  版本號 保持對齊
*//<code>

c. 屬性註解

在每個屬性前面必須加上屬性註釋，通常有一下兩種形式，至於怎麼選擇，你高興就好，不過一個項目中要保持統一。

<code>/** 提示信息 */
private String userName;
/**
 * 密碼
 */
private String password;/<code>

d. 方法註釋

在每個方法前面必須加上方法註釋，對於方法中的每個參數，以及返回值都要有說明。

<code>/**
  * 方法的詳細說明，能幹嘛，怎麼實現的，注意事項...
  *
  * @param xxx \t 參數1的使用說明， 能否為null
  * @return 返回結果的說明， 不同情況下會返回怎樣的結果
  * @throws 異常類型   註明從此類方法中拋出異常的說明
  *//<code>

e. 構造方法註釋

在每個構造方法前面必須加上註釋，註釋模板如下：

<code> /**
  * 構造方法的詳細說明 

  *
  * @param xxx \t 參數1的使用說明， 能否為null
  * @throws 異常類型   註明從此類方法中拋出異常的說明
  *//<code>

而簡單註解往往是需要工程師字節定義，在使用註解時應該注意一下幾點：

1. 枚舉類的各個屬性值都要使用註解，枚舉可以理解為是常量，通常不會發生改變，通常會被在多個地方引用，對枚舉的修改和添加屬性通常會帶來很大的影響。
2. 保持排版整潔，不要使用行尾註釋；雙斜槓和星號之後要用 1 個空格分隔。

<code>id = 1;// 反例：不要使用行尾註釋
//反例：換行符與註釋之間沒有縮進
int age = 18;
// 正例：姓名
String name;
/**
 * 1. 多行註釋
 *
 * 2. 對於不同的邏輯說明，可以用空行分隔
 *//<code>

總結

無論是命名和註解，他們的目的都是為了讓代碼和工程師進行對話，增強代碼的可讀性，可維護性。優秀的代碼往往能夠見名知意，註解往往是對命名的補充和完善。命名太南了！

閱讀更多 Java架構人生 的文章

關鍵字: 短語 形容詞 名詞