Java 代碼規範精要：命名、註釋、排版與編程 7 大維度

統一的代碼風格是團隊協作效率的基石。本文依據業界通用規範（Google Java Style、Alibaba Java 開發手冊），將 Java 編碼規範濃縮為 7 大維度 30+ 條核心準則，附違規/合規對比，可直接作為 Checkstyle/SpotBugs 規則配置參考。

1. 命名規範

禁用：單字母變量（除迴圈計數器）、拼音命名、中英混雜。

2. 註釋規範

• 文件註釋：每個源文件頂部必須有版權、作者、功能說明。
• 類/介面註釋：/** 核心職責描述 @author @since */
• 公共方法註釋：@param @return @throws 全覆蓋，main 方法除外。
• 字段註釋：非自顯義字段必須註釋業務含義。
• 行內註釋：用 // 解釋「為什麼」而非「做什麼」；區塊註釋用 /* */。
• 註釋密度 ≥ 15%，使用中文（團隊統一語言）。

3. 縮進排版

• 行寬 ≤ 120 字符（舊規範 80/60，現代寬屏建議放寬）。
• 統一用 4 空格縮進（禁用 Tab），IDE 設置 Ctrl+Shift+F 格式化。
• 關鍵字後加空格（if (cond)），運算符前後加空格。

4. 文件組織

• 一個源文件只定義一個公共類，文件名與類名一致。
• 類行數建議 ≤ 500 行（單一職責原則），超過拆分。
• 導入包不使用 * 通配，顯式導入；靜態導入僅用於常用工具方法。

5. 變量聲明

• 一行一聲明，就近聲明（用到時再聲明），初始化賦值。
• 避免局部變量遮蔽成員變量/上層變量。
• 方法間空一行分隔。

6. 語句規範

• if/for/while 必須加大括號，哪怕單行。
• return 不加括號：return value;
• for 初始化/更新子句變量 ≤ 2 個，複雜邏輯改用迭代器/流。
• switch 穿透需加 // fall through 註釋。

7. 編程實踐

• 封裝性：優先 private，提供 getter/setter；避免 protected/默認包可見性。
• 靜態成員用類名訪問（Math.PI），不可用實例訪問。
• 多重賦值拆分：a = b = 1; → 兩行。
• 多條件分支優先 switch / 策略模式，避免長 if-else 鏈。
• JDBC 必用 PreparedStatement 防注入，性能更優。
• 布爾 getter 用 isXxx()，其他用 getXxx()；setter 用 setXxx()。
• 消除魔術數字：定義 private static final int MAX_RETRY = 3;

工具落地

接入 Checkstyle（風格）、SpotBugs（缺陷）、PMD（最佳實踐）至 CI 流水線，配合 IDE 實時提示，讓規範「無感」執行。