Java 開發命名規範完整指南：套件、類別、變數與方法命名最佳實踐

前言：命名規範的重要性

在 Java 開發中，良好的命名規範是程式碼可讀性、可維護性與團隊協作的基石。Java 作為一門強型別、面向物件的語言，其命名慣例直接影響程式碼的專業度。本文系統整理 Java 核心命名規範，涵蓋套件、類別、介面、變數、常數、方法、Javadoc 註解等各層面，並提供實務應用範例，助你撰寫更優雅、規範的程式碼。

一、套件命名規範

核心原則

• 全小寫字母，單詞間不使用底線分隔
• 以組織的反向域名為前綴（如 com.company.project），確保全域唯一性
• 名稱需具備業務語意，清晰表達模組職責

分層架構下的套件結構

採用標準分層架構時，建議採用「域名反寫 + 業務模組 + 技術層」的三級結構：

com.company.user           // 用戶模組根套件
com.company.user.dao       // 資料存取層
com.company.user.service   // 業務邏輯層
com.company.user.web       // 控制層
com.company.user.entity    // 實體類別

二、類別與介面命名規範

類別命名

• 使用 名詞，採用 UpperCamelCase（帕斯卡命名法）：每個單字首字母大寫
• 名稱應準確、簡潔，優先使用完整單字，避免非通用縮寫
• 實現類建議加上 Impl 後綴區分介面：UserService / UserServiceImpl
• 實體類別不建議加後綴，直接使用領域名稱：User、Order

分層類別命名範例

介面命名

• 同樣採用 UpperCamelCase
• 除名詞外，可使用形容詞表達能力特徵：Serializable、Runnable、Comparable

三、變數命名規範

區域變數與成員變數

• 採用 lowerCamelCase（駝峰命名法）：首字母小寫，後續單字首字母大寫
• 名稱需表達業務含義，避免單字母（迴圈計數器 i、j、k 除外）
• 布林值建議用 is、has、can 開頭：isActive、hasPermission
• 集合類型建議加上複數後綴：userList、orderSet

常數命名

• 全大寫，單字間以底線分隔：MAX_CONNECTION_COUNT、DEFAULT_PAGE_SIZE
• 使用 static final 修飾

靜態變數

• 同常數規範：全大寫 + 底線分隔

四、方法命名規範

通用原則

• 採用 lowerCamelCase
• 首詞必須為動詞，表達行為動作：getUserById、calculateTotalAmount

各層方法命名約定

存取器方法

• Getter：get + 屬性名（首字母大寫），布林型可用 is 開頭
• Setter：set + 屬性名（首字母大寫）

五、Javadoc 註解規範

Javadoc 註解以 /** 開頭、*/ 結束，可自動生成 API 文件。建議對以下元素撰寫：

• 類別：整體用途、作者、版本、since 版本
• 欄位：業務含義、取值範圍
• 方法：功能描述、參數說明（@param）、返回值（@return）、拋出異常（@throws）

/**
 * 用戶服務介面，提供用戶相關業務操作
 *
 * @author Zhang San
 * @version 1.0
 * @since 2024-01-15
 */
public interface UserService {

    /**
     * 根據 ID 查詢用戶
     *
     * @param userId 用戶唯一標識
     * @return 用戶實體，不存在時返回 null
     * @throws BusinessException 業務異常
     */
    User getUserById(Long userId) throws BusinessException;
}

六、其他常見檔案命名規範

七、總結與建議

1. 一致性優於個人偏好：團隊應制定統一規範並透過 Checkstyle、SpotBugs 等工具強制執行
2. 名稱即文件：良好的命名能減少 80% 的註解需求
3. 拒絕縮寫：除非是領域通用術語（如 ID、URL、DTO），否則一律使用完整單字
4. 定期重構：隨著業務演進，及時重命名不再準確的識別符

記住：程式碼是給人看的，順便給機器執行。規範的命名是對未來維護者（包含未來的自己）最大的善意。