告別編碼5分鐘,命名2小時(shí)!史上超全的Java命名規(guī)范參考!

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

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

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

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

二，包命名

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

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

三，類命名

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

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

四，方法

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

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

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

位置	單詞	意義	例
pre	is	對(duì)象是否符合期待的狀態(tài)	isValid
pre	can	對(duì)象能否執(zhí)行所期待的動(dòng)作	canRemove
pre	should	調(diào)用方執(zhí)行某個(gè)命令 或方法是好還是不好 應(yīng)不應(yīng)該， 或者說推薦還是不推薦	shouldMigrate
pre	has	對(duì)象是否持有 所期待的數(shù)據(jù)和屬性	hasObservers
pre	needs	調(diào)用方是否需要 執(zhí)行某個(gè)命令或方法	needsMigrate

4.2 用來檢查的方法

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

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

4.5 回調(diào)方法

4.6 操作對(duì)象生命周期的方法

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

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

4.9 成對(duì)出現(xiàn)的動(dòng)詞

五，變量&常量命名

5.1 變量命名

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

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

5.2 常量命名

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

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

1. /**

2. * 一個(gè)demo

3. *

4. * @author Jann Lee

5. * @date 2019-12-07 00:25

6. **/

7. publicclassHelloWorld{

8. 
   

9. /**

10. * 局部常量(正例)

11. */

12. publicstaticfinallong USER_MESSAGE_CACHE_EXPIRE_TIME =3600;

13. 
    

14. /**

15. * 局部常量(反例，命名不清晰）

16. */

17. publicstaticfinallong MESSAGE_CACHE_TIME =3600;

18. 
    

19. /**

20. * 全局常量

21. */

22. privatestaticfinalString ERROR_MESSAGE =" error message";

23. 
    

24. /**

25. * 成員變量

26. */

27. privateint currentUserId;

28. 
    

29. /**

30. * 控制臺(tái)打印 {@code message} 信息

31. *

32. * @param message 消息體，局部常量

33. */

34. publicvoid sayHello(finalString message){

35. System.out.println("Hello world!");

36. }

37. 
    

38. }

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

通用命名規(guī)則

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

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

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

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

六，代碼注解

6.1 注解的原則

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

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

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

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

2. getMessageById(id)

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

6.2 注解格式

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

a. 包注解

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

1. /**

2. * 落地也質(zhì)量檢測(cè)

3. * 1. 用來解決什么問題

4. * 對(duì)廣告主投放的廣告落地頁進(jìn)行性能檢測(cè)，模擬不同的系統(tǒng)，如Android，IOS等; 模擬不同的網(wǎng)絡(luò)：2G，3G，4G，wifi等

5. *

6. * 2. 如何實(shí)現(xiàn)

7. * 基于chrome瀏覽器，用chromedriver驅(qū)動(dòng)瀏覽器，設(shè)置對(duì)應(yīng)的網(wǎng)絡(luò)，OS參數(shù)，獲取到瀏覽器返回結(jié)果。

8. *

9. * 注意：網(wǎng)絡(luò)環(huán)境配置信息{@link cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}目前使用是常規(guī)速度，可以根據(jù)實(shí)際情況進(jìn)行調(diào)整

10. *

11. * @author cruder

12. * @time 2019/12/7 20:3 下午

13. */

14. package cn.mycookies.landingpagecheck;

b. 類注接

javadoc注解中，每個(gè)類都必須有注解。

1. /**

2. * Copyright (C), 2019-2020, Jann balabala...

3. *

4. * 類的介紹：這是一個(gè)用來做什么事情的類，有哪些功能，用到的技術(shù).....

5. *

6. * @author 類創(chuàng)建者姓名 保持對(duì)齊

7. * @date 創(chuàng)建日期 保持對(duì)齊

8. * @version 版本號(hào) 保持對(duì)齊

9. */

c. 屬性注解

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

1. /** 提示信息 */

2. privateString userName;

3. /**

4. * 密碼

5. */

6. privateString password;

d. 方法注釋

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

1. /**

2. * 方法的詳細(xì)說明，能干嘛，怎么實(shí)現(xiàn)的，注意事項(xiàng)...

3. *

4. * @param xxx 參數(shù)1的使用說明， 能否為null

5. * @return 返回結(jié)果的說明， 不同情況下會(huì)返回怎樣的結(jié)果

6. * @throws 異常類型 注明從此類方法中拋出異常的說明

7. */

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

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

1. /**

2. * 構(gòu)造方法的詳細(xì)說明

3. *

4. * @param xxx 參數(shù)1的使用說明， 能否為null

5. * @throws 異常類型 注明從此類方法中拋出異常的說明

6. */

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

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

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

1. int id =1;// 反例：不要使用行尾注釋

2. //反例：換行符與注釋之間沒有縮進(jìn)

3. int age =18;

4. // 正例：姓名

5. String name;

6. /**

7. * 1. 多行注釋

8. *

9. * 2. 對(duì)于不同的邏輯說明，可以用空行分隔

10. */

總結(jié)

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

參考文獻(xiàn)：《碼出高效》
https://www.cnblogs.com/wangcp-2014/p/10215620.html
https://qiita.com/KeithYokoma/items/2193cf79ba76563e3db6
https://google.github.io/styleguide/javaguide.html#s2.1-file-name

推薦閱讀：

• 這個(gè)時(shí)代，達(dá)不到百萬級(jí)以上的并發(fā)量，都不叫高并發(fā)！！！
  

• Spring Cloud Hoxton正式發(fā)布，Spring Boot 2.2.x不再孤單
  

• 程序員必備效率神器，你用過幾個(gè)？
  

• 大白話帶你認(rèn)識(shí)Kafka
  

喜歡我可以給我設(shè)為星標(biāo)哦

好文章，我?在看?