Java 編碼規範全景指南：命名約定、註釋標準與最佳實踐

一、命名約定 — 代碼即文檔

通用原則

• 完整英文單詞，拒絕拼音/縮寫 (除領域通用術語：ID、URL、HTML、SQL、CPU)。
• 駝峰命名：類/接口 PascalCase，方法/變量 camelCase，常量 UPPER_SNAKE_CASE。
• 長度 < 15 字符 (特殊領域類名可放寬)。
• 避免相似名稱 (如 data/date、userList/userLists)。
• 無下劃線 (除常量、JNI、序列化 serialVersionUID)。

分類命名標準表

二、註釋約定 — 解釋「為什麼」而非「做什麼」

核心原則

1. 註釋提升清晰度，而非噪音。
2. 保持簡潔，過時註釋立即刪除/更新。
3. 先寫註釋再寫代碼 (契約先行)。
4. 註釋意圖/決策/業務規則，代碼自述實現細節。

註釋類型與範例

必須註釋的場景

• 類：目的、不變量、線程安全級別、設計模式角色。
• 接口：契約語義、實現約束、使用/禁用示例。
• 公共方法：做什麼、參數含義/約束、返回值語義、拋出異常條件、副作用、性能特徵。
• 複雜邏輯塊：算法步驟、業務規則來源、邊界條件處理。
• 參數：業務含義、合法範圍、空值語義。

Get/Set 方法註釋簡化規則

字段已有完整文檔註釋時，對應 Get/Set 可省略或僅加 @return/@param 簡略標註。

三、現代化工具鏈落地

• Checkstyle / SpotBugs / PMD：CI 流水線強制掃描命名、註釋、復雜度。
• Google Java Format / Eclipse Formatter：統一格式化，消除風格爭論。
• ArchUnit：架構層面規則驗證 (如：Controller 不直接訪問 Repository)。
• IDE 實時檢查：IntelliJ Inspection、Eclipse Save Actions 自動修復。

四、團隊協約建議

1. 建立《項目編碼規範》Markdown 文件，納入版本控制，新人入職必讀。
2. Code Review 清單包含命名/註釋檢查項，工具自動化覆蓋 80%+。
3. 定期回顧規範，吸收新語言特性 (如 Record、Sealed Class、Pattern Matching) 更新標準。
4. 原則：一致性 > 個人偏好，統一風格降低認知負荷，提升團隊協作效率。

良好的命名與註釋，是代碼給未來維護者 (包括 6 個月後的自己) 寫的情書。