Effective Java Item 68：遵守普遍接受的命名規則
整理 Effective Java 書中 Item 68: Adhere to generally accepted naming conventions 心得筆記
主旨
命名風格看似枝微末節，卻是團隊協作與程式維護的關鍵。Java 本身就訂立了明確的命名規則（來自 JLS 6.1），包括 字型格式（typographical） 和 語法規則（grammatical） 兩大類。違反這些規則不僅會讓程式碼難讀、難維護，甚至可能誤導其他開發者造成 bug。
➡️ 命名規範不該是選項，而該是寫 Java 時的直覺反應。
字型命名規則（Typographical Conventions）
| 類型 | 命名格式範例 | 備註 |
|---|---|---|
| Package/module | org.junit.jupiter.api, com.google.util | 小寫、以反轉的網域為開頭 |
| Class/Interface | HashMap, FutureTask, HttpClient | 每字首大寫，不用縮寫 |
| Method/Field | remove, getCrc, isEmpty | 首字小寫，其餘單字開頭大寫 |
| Constant Field | MAX_VALUE, NEGATIVE_INFINITY | 全大寫 + 底線分隔，只限常數使用 |
| Local Variable | i, count, tmpStr | 可使用縮寫或單字母（依情境） |
| Type Parameter | T, E, K, V, R, X | 通用模板規範字母 |
✅ 唯一可接受底線用法：static final 常數欄位名稱
語法命名規則（Grammatical Conventions）
Package 名稱
- 小寫，以反轉的網域開頭，如
com.example.project - 一般用一至兩層，不需強調階層語意
Class / Interface / Enum / Annotation
- 使用 單數名詞：
Thread,PriorityQueue,ChessPiece - 工具類可用複數：
Collections,Collectors - Interface 也用名詞或
-able/-ible結尾形容詞：Runnable,Iterable
Method 命名
- 動作動詞或動詞片語：
append,drawImage - Boolean 方法 →
is/has開頭：isEnabled,hasChild - Getter 方法：
- 傳統風格：
size(),name() - JavaBeans 風格：
getName(),setName()
- 傳統風格：
- 特殊用途命名：
- 轉型：
toString,toArray - 視圖：
asList - 原始值：
intValue,longValue - 工廠方法：
of,from,valueOf,newInstance
- 轉型：
Field 命名
- Boolean 欄位：
enabled,visible（省略 is） - 其他型別欄位：名詞或名詞片語，例如
height,digits - 建議盡量減少 public 欄位，否則要更謹慎命名
Local Variable 命名
- 可使用語境適合的縮寫：
i,tmp,buf - 但對於參數名稱建議完整清楚：
startIndex,maxRetries
小技巧與提醒
| 場景 | 建議命名方式 |
|---|---|
| 多單字的 class 名稱 | 每字首大寫：LinkedHashMap |
| HTTP URL 的命名 | 建議：HttpUrl（避免全大寫） |
| Type parameter 用法 | 泛型 T, E, K, V, R 對應語意明確 |
| getter/setter 命名對應 | getName() ↔ setName(String) |
| 測試命名 | shouldReturnEmptyList_whenInputIsNull()（有語意） |
為什麼這很重要？
- 統一風格 → 降低學習與維護成本
- 違反規則 → 容易誤解、造成錯誤使用
- 團隊合作 → 建立信任與一致的代碼品質
- 工具與框架 → 很多自動化工具仰賴命名規則
小結
| 建議 | 說明 |
|---|---|
| ✅ 字型規則請完整遵守 | 比如方法小寫開頭、類別大寫開頭等 |
| ✅ 語法命名要語意清楚有一致性 | 動詞動作 vs. 名詞屬性請分清楚 |
| ✅ 不要為追求酷炫自創命名風格 | 工程不是藝術，要先可讀、可維護 |
| ✅ 熟悉 Java 常見命名模式 | IDE、工具、框架常仰賴這些規則運作 |
Read other posts