编码5分钟,命名2小时?Java开发都需要参考的一份命名规范!
簡潔清爽的代碼風格應該是大多數工程師所期待的。在工作中筆者常常因為起名字而糾結,命名已經成為我工作中的攔路虎,夸張點可以說是編程5分鐘,命名兩小時!
每個公司都有不同的標準,目的是為了保持統一,減少溝通成本,提升團隊研發效能。所以本文中是筆者結合阿里巴巴開發規范,以及工作中的見聞針對Java領域相關命名進行整理和總結,僅供參考。
一,Java中的命名規范
好的命名能體現出代碼的特征,含義或者是用途,讓閱讀者可以根據名稱的含義快速厘清程序的脈絡。不同語言中采用的命名形式大相徑庭,Java中常用到的命名形式共有三種,既首字母大寫的UpperCamelCase,首字母小寫的lowerCamelCase以及全部大寫的并用下劃線分割單詞的UPPERCAMELUNSER_SCORE。通常約定,類一般采用大駝峰命名,方法和局部變量使用小駝峰命名,而大寫下劃線命名通常是常量和枚舉中使用。
| 項目 | 全部小寫 多個單詞用中劃線分隔‘-’ | spring-cloud |
| 包 | 全部小寫 | com.alibaba.fastjson |
| 類 | 單詞首字母大寫 | Feature, FieldDeserializer |
| 變量 | 首字母小寫 多個單詞組成時, 除首個單詞 其他單詞首字母都要大寫 | password,? userName |
| 常量 | 全部大寫,多個單詞,用'_'分隔 | CACHEEXPIREDTIME |
| 方法 | 同變量 | read(),? getById(Long id) |
二,包命名
包名統一使用小寫,點分隔符之間有且僅有一個自然語義的英文單詞或者多個單詞自然連接到一塊(如 springframework,deepspace不需要使用任何分割)。包名統一使用單數形式,如果類命有復數含義,則可以使用復數形式。
包名的構成可以分為以下幾四部分【前綴】 【發起者名】【項目名】【模塊名】。常見的前綴可以分為以下幾種:
| indi 或 onem | indi.發起者名.項目名.模塊名.…… | 個體項目 個人發起,但非自己獨自完成 可公開或私有項目, copyright主要屬于發起者。 |
| pers | pers.個人名.項目名.模塊名.…… | 個人項目 指個人發起,獨自完成, 可分享的項目 copyright主要屬于個人 |
| priv | priv.個人名.項目名.模塊名.…… | 私有項目,指個人發起,獨自完成 非公開的私人使用的項目, copyright屬于個人。 |
| team | team.團隊名.項目名.模塊名.…… | 團隊項目,指由團隊發起 并由該團隊開發的項目 copyright屬于該團隊所有 |
| 頂級域名 | com.公司名.項目名.模塊名.…… | 公司項目 copyright由項目發起的公司所有 |
三,類命名
類名使用大駝峰命名形式,類命通常時名詞或名詞短語,接口名除了用名詞和名詞短語以外,還可以使用形容詞或形容詞短語,如Cloneable,Callable等,表示實現該接口的類有某種功能或能力。對于測試類則以它要測試的類開頭,以Test結尾,如HashMapTest。
對于一些特殊特有名詞縮寫也可以使用全大寫命名,比如XMLHttpRequest,不過筆者認為縮寫三個字母以內都大寫,超過三個字母則按照要給單詞算。這個沒有標準如阿里巴巴中fastjson用JSONObject作為類命,而google則使用JsonObjectRequest命名,對于這種特殊的縮寫,原則是統一就好。
| 抽象 | Abstract? 或 Base 開頭 | BaseUserService |
| 枚舉 | Enum 作為后綴 | OSType |
| 工具 | Utils作為后綴 | StringUtils |
| 異常 | Exception結尾 | RuntimeException |
| 接口實現 | 接口名+ Impl | UserServiceImpl |
| 領域模型相 | /DO/DTO/VO/DAO | 正例:UserDAO 反例:UserDao |
| 設計模式相關 | Builder,Factory等 | 當使用到設計模式時 要使用對應的設計模式作為后綴 如ThreadFactory |
| 處理特定功能 | Handler,Predicate Validator | 表示處理器,校驗器,斷言 這些類工廠還有配套的方法名 如handle,predicate,validate |
| 測試 | Test后綴 | UserServiceTest 表示用來測試UserService類的 |
| MVC分層 | Controller,Service ServiceImpl,DAO 后綴 | UserManageController UserManageDAO |
四,方法
方法命名采用小駝峰的形式,首字小寫,往后的每個單詞首字母都要大寫。和類名不同的是,方法命名一般為動詞或動詞短語,與參數或參數名共同組成動賓短語,即動詞 + 名詞。一個好的函數名一般能通過名字直接獲知該函數實現什么樣的功能。
4.1 返回真偽值的方法
注:pre- prefix前綴,suf- suffix后綴,alo-alone 單獨使用
| pre | is | 對象是否符合期待的狀態 | isValid |
| pre | can | 對象能否執行所期待的動作 | canRemove |
| pre | should | 調用方執行某個命令 或方法是好還是不好 應不應該, 或者說推薦還是不推薦 | shouldMigrate |
| pre | has | 對象是否持有 所期待的數據和屬性 | hasObservers |
| pre | needs | 調用方是否需要 執行某個命令或方法 | needsMigrate |
4.2 用來檢查的方法
| ensure | 檢查是否為期待的狀態 不是則拋出異常或返回error code | ensureCapacity |
| validate | 檢查是否為正確的狀態 不是則拋出異常或返回error code | validateInputs |
4.3 按需求才執行的方法
| suf | IfNeeded | 需要的時候執行 不需要則什么都不做 | drawIfNeeded |
| pre | might | 同上 | mightCreate |
| pre | try | 嘗試執行 失敗時拋出異常 或是返回errorcode | tryCreate |
| suf | OrDefault | 嘗試執行 失敗時返回默認值 | getOrDefault |
| suf | OrElse | 嘗試執行 失敗時返回 實際參數中指定的值 | getOrElse |
| pre | force | 強制嘗試執行 error拋出異常或是返回值 | forceCreate,? forceStop |
4.4 異步相關方法
| pre | blocking | 線程阻塞方法 | blockingGetUser |
| suf | InBackground | 執行在后臺線程 | doInBackground |
| suf | Async | 異步方法 | sendAsync |
| suf | Sync | 同步方法 | sendSync |
pre | schedule | Job和Tas | schedule,? scheduleJob |
pre | post | 同上 | postJob |
pre | execute | 執行異步 | execute, executeTask |
pre | start | 同上 | star, |
pre | cancel | 停止異步方法 | cance, |
pre | stop | 同上 | stop, stopJob |
4.5 回調方法
| pre | on | 事件發生時執行 | onCompleted |
| pre | before | 事件發生前執行 | beforeUpdate |
| pre | pre | 同上 | preUpdate |
| pre | will | 同上 | willUpdate |
| pre | after | 事件發生后執行 | afterUpdate |
| pre | post | 同上 | postUpdate |
| pre | did | 同上 | didUpdate |
| pre | should | 確認事件 是否可以執行 | shouldUpdate |
4.6 操作對象生命周期的方法
| initialize | 初始化或延遲初始化使用 | initialize |
| pause | 暫停 | onPause , pause |
| stop | 停止 | onStop, stop |
| abandon | 銷毀的替代 | abandon |
| destroy | 同上 | destroy |
| dispose | 同上 | dispose |
4.7 與集合操作相關的方法
| contains | 是包含指定對象相同的對象 | contains |
| add | 添加 | addJob |
| append | 添加 | appendJob |
| insert | 插入到下標n | insertJob |
| put | 添加與key對應的元素 | putJob |
| remove | 移除元素 | removeJob |
| enqueue | 添加到隊列的最末位 | enqueueJob |
| dequeue | 從隊列中頭部取出并移除 | dequeueJob |
| push | 添加到棧頭 | pushJob |
| pop | 從棧頭取出并移除 | popJob |
| peek | 從棧頭取出但不移除 | peekJob |
| find | 尋找符合條件的某物 | findById |
4.8 與數據相關的方法
| create | 新創建 | createAccount |
| new | 新創建 | newAccount |
| from | 從既有的某物新建 或是從其他的數據新建 | fromConfig |
| to | 轉換 | toString |
| update | 更新既有某物 | updateAccount |
| load | 讀取 | loadAccount |
| fetch | 遠程讀取 | fetchAccount |
| delete | 刪除 | deleteAccount |
| remove | 刪除 | removeAccount |
| save | 保存 | saveAccount |
| store | 保存 | storeAccount |
| commit | 保存 | commitChange |
| apply | 保存或應用 | applyChange |
| clear | 清除或是恢復到初始狀態 | clearAll |
| reset | 清除或是恢復到初始狀態 | resetAll |
4.9 成對出現的動詞
| get獲取 | set 設置 |
| add 增加 | remove 刪除 |
| create 創建 | destory 移除 |
| start 啟動 | stop 停止 |
| open 打開 | close 關閉 |
| read 讀取 | write 寫入 |
| load 載入 | save 保存 |
| create 創建 | destroy 銷毀 |
| begin 開始 | end 結束 |
| backup 備份 | restore 恢復 |
| import 導入 | export 導出 |
| split 分割 | merge 合并 |
| inject 注入 | extract 提取 |
| attach 附著 | detach 脫離 |
| bind 綁定 | separate 分離 |
| view 查看 | browse 瀏覽 |
| edit 編輯 | modify 修改 |
| select 選取 | mark 標記 |
| copy 復制 | paste 粘貼 |
| undo 撤銷 | redo 重做 |
| insert 插入 | delete 移除 |
| add 加入 | append 添加 |
| clean 清理 | clear 清除 |
| index 索引 | sort 排序 |
| find 查找 | search 搜索 |
| increase 增加 | decrease 減少 |
| play 播放 | pause 暫停 |
| launch 啟動 | run 運行 |
| compile 編譯 | execute 執行 |
| debug 調試 | trace 跟蹤 |
| observe 觀察 | listen 監聽 |
| build 構建 | publish 發布 |
| input 輸入 | output 輸出 |
| encode 編碼 | decode 解碼 |
| encrypt 加密 | decrypt 解密 |
| compress 壓縮 | decompress 解壓縮 |
| pack 打包 | unpack 解包 |
| parse 解析 | emit 生成 |
| connect 連接 | disconnect 斷開 |
| send 發送 | receive 接收 |
| download 下載 | upload 上傳 |
| refresh 刷新 | synchronize 同步 |
| update 更新 | revert 復原 |
| lock 鎖定 | unlock 解鎖 |
| check out 簽出 | check in 簽入 |
| submit 提交 | commit 交付 |
| push 推 | pull 拉 |
| expand 展開 | collapse 折疊 |
| begin 起始 | end 結束 |
| start 開始 | finish 完成 |
| enter 進入 | exit 退出 |
| abort 放棄 | quit 離開 |
| obsolete 廢棄 | depreciate 廢舊 |
| collect 收集 | aggregate 聚集 |
五,變量&常量命名
5.1 變量命名
變量是指在程序運行中可以改變其值的量,包括成員變量和局部變量。變量名由多單詞組成時,第一個單詞的首字母小寫,其后單詞的首字母大寫,俗稱駱駝式命名法(也稱駝峰命名法),如 computedValues,index、變量命名時,盡量簡短且能清楚的表達變量的作用,命名體現具體的業務含義即可。
變量名不應以下劃線或美元符號開頭,盡管這在語法上是允許的。變量名應簡短且富于描述。變量名的選用應該易于記憶,即,能夠指出其用途。盡量避免單個字符的變量名,除非是一次性的臨時變量。pojo中的布爾變量,都不要加is(數據庫中的布爾字段全都要加 is_ 前綴)。
5.2 常量命名
常量命名CONSTANT_CASE,一般采用全部大寫(作為方法參數時除外),單詞間用下劃線分割。那么什么是常量呢?
常量是在作用域內保持不變的值,一般使用final進行修飾。一般分為三種,全局常量(public static final修飾),類內常量(private static final 修飾)以及局部常量(方法內,或者參數中的常量),局部常量比較特殊,通常采用小駝峰命名即可。
/*** 一個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!");} }常量一般都有自己的業務含義,不要害怕長度過長而進行省略或者縮寫。如,用戶消息緩存過期時間的表示,那種方式更佳清晰,交給你來評判。
通用命名規則
盡量不要使用拼音;杜絕拼音和英文混用。對于一些通用的表示或者難以用英文描述的可以采用拼音,一旦采用拼音就堅決不能和英文混用。正例:BeiJing, HangZhou 反例:validateCanShu
命名過程中盡量不要出現特殊的字符,常量除外。
盡量不要和jdk或者框架中已存在的類重名,也不能使用java中的關鍵字命名。
妙用介詞,如for(可以用同音的4代替), to(可用同音的2代替), from, with,of等。如類名采用User4RedisDO,方法名getUserInfoFromRedis,convertJson2Map等。
六,代碼注解
6.1 注解的原則
好的命名增加代碼閱讀性,代碼的命名往往有嚴格的限制。而注解不同,程序員往往可以自由發揮,單并不意味著可以為所欲為之胡作非為。優雅的注解通常要滿足三要素。
Nothing is strange 沒有注解的代碼對于閱讀者非常不友好,哪怕代碼寫的在清除,閱讀者至少從心理上會有抵觸,更何況代碼中往往有許多復雜的邏輯,所以一定要寫注解,不僅要記錄代碼的邏輯,還有說清楚修改的邏輯。
Less is more 從代碼維護角度來講,代碼中的注解一定是精華中的精華。合理清晰的命名能讓代碼易于理解,對于邏輯簡單且命名規范,能夠清楚表達代碼功能的代碼不需要注解。濫用注解會增加額外的負擔,更何況大部分都是廢話。
Advance with the time 注解應該隨著代碼的變動而改變,注解表達的信息要與代碼中完全一致。通常情況下修改代碼后一定要修改注解。
6.2 注解格式
注解大體上可以分為兩種,一種是javadoc注解,另一種是簡單注解。javadoc注解可以生成JavaAPI為外部用戶提供有效的支持javadoc注解通常在使用IDEA,或者Eclipse等開發工具時都可以自動生成,也支持自定義的注解模板,僅需要對對應的字段進行解釋。參與同一項目開發的同學,盡量設置成相同的注解模板。
a. 包注解
包注解在工作中往往比較特殊,通過包注解可以快速知悉當前包下代碼是用來實現哪些功能,強烈建議工作中加上,尤其是對于一些比較復雜的包,包注解一般在包的根目錄下,名稱統一為package-info.java。
/*** 落地也質量檢測* 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;b. 類注接
javadoc注解中,每個類都必須有注解。
/** * Copyright (C), 2019-2020, Jann balabala... * * 類的介紹:這是一個用來做什么事情的類,有哪些功能,用到的技術..... * * @author 類創建者姓名 保持對齊 * @date 創建日期 保持對齊 * @version 版本號 保持對齊 */c. 屬性注解
在每個屬性前面必須加上屬性注釋,通常有一下兩種形式,至于怎么選擇,你高興就好,不過一個項目中要保持統一。
/** 提示信息 */ private String userName; /*** 密碼*/ private String password;d. 方法注釋
在每個方法前面必須加上方法注釋,對于方法中的每個參數,以及返回值都要有說明。
/*** 方法的詳細說明,能干嘛,怎么實現的,注意事項...** @param xxx 參數1的使用說明, 能否為null* @return 返回結果的說明, 不同情況下會返回怎樣的結果* @throws 異常類型 注明從此類方法中拋出異常的說明*/e. 構造方法注釋
在每個構造方法前面必須加上注釋,注釋模板如下:
/*** 構造方法的詳細說明** @param xxx 參數1的使用說明, 能否為null* @throws 異常類型 注明從此類方法中拋出異常的說明*/而簡單注解往往是需要工程師字節定義,在使用注解時應該注意一下幾點:
枚舉類的各個屬性值都要使用注解,枚舉可以理解為是常量,通常不會發生改變,通常會被在多個地方引用,對枚舉的修改和添加屬性通常會帶來很大的影響。
保持排版整潔,不要使用行尾注釋;雙斜杠和星號之后要用1個空格分隔。
總結
無論是命名和注解,他們的目的都是為了讓代碼和工程師進行對話,增強代碼的可讀性,可維護性。優秀的代碼往往能夠見名知意,注解往往是對命名的補充和完善。命名太南了!
參考文獻:《碼出高效》
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
- MORE | 更多精彩文章 -
B站沒有天敵
一文講透Dubbo負載均衡之最小活躍數算法
不扯概念,用例子演示什么是臟讀,不可重復讀,幻讀?
面試必問:用 Java 寫一個內存泄漏程序
如果你喜歡本文,
請長按二維碼,關注?Hollis.
轉發至朋友圈,是對我最大的支持。
好文章,我在看??
總結
以上是生活随笔為你收集整理的编码5分钟,命名2小时?Java开发都需要参考的一份命名规范!的全部內容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: 一篇文章带你搞定和Spring Boot
- 下一篇: [算法学习]斐波那契数的计算