編碼5分鐘，命名2小時？Java開發(fā)都需要參考的一份命名規(guī)范

簡潔清爽的代碼風(fēng)格應(yīng)該是大多數(shù)工程師所期待的。在工作中筆者常常因為起名字而糾結(jié)，命名已經(jīng)成為我工作中的攔路虎，夸張點可以說是編程5分鐘，命名兩小時！

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

一，Java中的命名規(guī)范

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

二，包命名

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

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

三，類命名

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

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

四，方法

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

4.1 返回真?zhèn)沃档姆椒?/h4>

注：pre- prefix前綴，suf- suffix后綴，alo-alone 單獨使用

4.2 用來檢查的方法

4.3 按需求才執(zhí)行的方法

4.4 異步相關(guān)方法

4.5 回調(diào)方法

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

4.7 與集合操作相關(guān)的方法

4.8 與數(shù)據(jù)相關(guān)的方法

4.9 成對出現(xiàn)的動詞

五，變量&常量命名

5.1 變量命名

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

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

5.2 常量命名

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

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

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

通用命名規(guī)則

1. 盡量不要使用拼音；杜絕拼音和英文混用。對于一些通用的表示或者難以用英文描述的可以采用拼音，一旦采用拼音就堅決不能和英文混用。正例：BeiJing， HangZhou 反例：validateCanShu

2. 命名過程中盡量不要出現(xiàn)特殊的字符，常量除外。

3. 盡量不要和jdk或者框架中已存在的類重名，也不能使用java中的關(guān)鍵字命名。

4. 妙用介詞，如for(可以用同音的4代替), to(可用同音的2代替), from, with，of等。如類名采用User4RedisDO，方法名getUserInfoFromRedis，convertJson2Map等。

六，代碼注解

6.1 注解的原則

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

1. Nothing is strange 沒有注解的代碼對于閱讀者非常不友好，哪怕代碼寫的在清除，閱讀者至少從心理上會有抵觸，更何況代碼中往往有許多復(fù)雜的邏輯，所以一定要寫注解，不僅要記錄代碼的邏輯，還有說清楚修改的邏輯。

2. Less is more 從代碼維護角度來講，代碼中的注解一定是精華中的精華。合理清晰的命名能讓代碼易于理解，對于邏輯簡單且命名規(guī)范，能夠清楚表達代碼功能的代碼不需要注解。濫用注解會增加額外的負擔(dān)，更何況大部分都是廢話。

//?根據(jù)id獲取信息【廢話注解】getMessageById(id)

1. Advance with the time 注解應(yīng)該隨著代碼的變動而改變，注解表達的信息要與代碼中完全一致。通常情況下修改代碼后一定要修改注解。

6.2 注解格式

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

a. 包注解

包注解在工作中往往比較特殊，通過包注解可以快速知悉當前包下代碼是用來實現(xiàn)哪些功能，強烈建議工作中加上，尤其是對于一些比較復(fù)雜的包，包注解一般在包的根目錄下，名稱統(tǒng)一為package-info.java。

/**?*?落地也質(zhì)量檢測?*?1.?用來解決什么問題?*?對廣告主投放的廣告落地頁進行性能檢測，模擬不同的系統(tǒng)，如Android，IOS等;?模擬不同的網(wǎng)絡(luò)：2G，3G，4G，wifi等?*?*?2.?如何實現(xiàn)?*?基于chrome瀏覽器，用chromedriver驅(qū)動瀏覽器，設(shè)置對應(yīng)的網(wǎng)絡(luò)，OS參數(shù)，獲取到瀏覽器返回結(jié)果。?*?*?注意：網(wǎng)絡(luò)環(huán)境配置信息{@link?cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常規(guī)速度，可以根據(jù)實際情況進行調(diào)整?*?*?@author?cruder?*?@time?2019/12/7?20:3?下午?*/package?cn.mycookies.landingpagecheck;

b. 類注接

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

c. 屬性注解

在每個屬性前面必須加上屬性注釋，通常有一下兩種形式，至于怎么選擇，你高興就好，不過一個項目中要保持統(tǒng)一。

d. 方法注釋

在每個方法前面必須加上方法注釋，對于方法中的每個參數(shù)，以及返回值都要有說明。

e. 構(gòu)造方法注釋

在每個構(gòu)造方法前面必須加上注釋，注釋模板如下：

而簡單注解往往是需要工程師字節(jié)定義，在使用注解時應(yīng)該注意一下幾點：

1. 枚舉類的各個屬性值都要使用注解，枚舉可以理解為是常量，通常不會發(fā)生改變，通常會被在多個地方引用，對枚舉的修改和添加屬性通常會帶來很大的影響。

2. 保持排版整潔，不要使用行尾注釋；雙斜杠和星號之后要用1個空格分隔。

總結(jié)

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