Java 代碼審查規範完整指南：命名、註解、可靠性、效能與 SQL 優化

Java 代碼審查規範完整指南：命名、註解、可靠性、效能與 SQL 優化

代碼審查是保障專案品質、降低技術債的關鍵環節。本文整理涵蓋命名規範、註解標準、聲明與縮排、語句分佈、可靠性檢查、可維護性、可讀性、效能優化、日誌規範、圈複雜度控制及 SQL 編寫優化等 11 大維度的完整檢查清單，供團隊落地執行。

一、命名規範

• 統一風格： 成員變數、方法參數採用 lowerCamelCase，禁用下劃線、數字開頭。
• 見名知意： 遵循「最小長度、最大資訊」原則，除 to→2、for→4 外，不建議在命名中混入數字。
• 布林前綴： has/can/is 開頭的方法必須返回 boolean；變數若為布林型，建議移除前綴（如 isValid → valid）。
• 避免重名： 自定義類別勿與第三方庫、JDK 類別同名，尤其注意子類與父類同名問題。

二、註文規範

• Javadoc 必備： 所有 public/protected 類別、介面、方法、欄位必須有 Javadoc，說明功能、參數、返回值、異常。
• 複雜邏輯註解： 分支嵌套超 3 層、跨行較遠的右大括號、特殊業務邏輯、非常規用法均需行內註解。
• 註解率： 目標 30%~60%，避免過度或缺失。

三、聲明、空白與縮排

• 每行僅宣告一個變數，定義即初始化。
• 類屬性必須初始化；區域變數使用前賦值。
• 空行分隔邏輯區塊；運算符前後、括號附近保留空格。
• 單行不超 120 字元；巢狀縮排不超 4 層（含 try/for/while/switch/if）。
• Controller/Service/DAO 禁用有狀態變數，若必須修改需加鎖。
• 集合必須定義泛型，減少轉型與警告。

四、語句與功能分佈

• 所有 if/else/for/while/case 區塊強制加大括號。
• 單一變數單一用途；單行單一功能，禁用分號合併多句。
• 方法單一職責，命名與行為一致。
• ++/-- 運算符不參與複雜表達式。
• 方法行數建議 ≤30 行，上限 60 行；類建議 ≤500 行，上限 1000 行。
• 方法參數 ≤5 個，上限 7 個；方法調用深度 ≤15 層。

五、可靠性核心檢查

總則與變數

• 消除所有編譯/IDE 警告；常數聲明 final。
• 物件使用前必須非空檢查；try 區塊內賦值的物件，調用也必須在 try 內。
• 區域集合/陣列/Map 使用後建議置 null 釋放引用。
• 陣列存取必須邊界檢查；嚴禁區域變數與成員變數同名。
• 比較採用 常量 == 變數 或 常量.equals(變數) 防空指針與誤賦值。
• 每組 if-else if 必有終結 else；switch 必有 default。
• 迴圈採用半開區間 i=0; i<MAX。
• XML 標籤完整、字串拼接正確；流操作 finally 關閉並判空。
• 浮點數禁用 ==，提供通用比較工具；物件比較統一用 equals 且確保類型一致。
• Map/Properties/Session/Request 的 Key 定義為常數，禁用硬編碼字串。
• 類型轉換前確保相容；包裝類運算前非空判斷。
• 唯讀屬性必須有賦值途徑；方法調用前做參數非空驗證（由呼叫端保證）。
• DateFormat 等非線程安全物件禁用 static，改用 ThreadLocal。
• 跨實體同義欄位命名統一（如 userName 而非混用 username）。

方法層面

• 入參非空、合法範圍雙重校驗；拋出異常的方法外層必包 try-catch。
• 所有分支必有返回值；int 返回值約定：負值失敗、非負成功。
• 重複返回值判斷封裝為工具方法；關鍵碼捕獲異常並記錄/拋出。
• 異常捕獲後：無法處理→繼續拋出；可處理→記錄日誌。
• 構造器禁用 new this()；同步集合遍歷期間禁增刪元素（拋 ConcurrentModificationException）。
• 線程 run() 迴圈內必捕獲異常防退出；原子操作中斷需回滾外部狀態。

六、可維護性

• 消除魔術數字（-2~10 除外），改用常數 static final。
• 消除連續賦值導致的結構模糊（如 a = (b = d + c)）。
• 正確使用日誌等級；消除冗餘判斷（if(b) return true; else return false; → return b;）。
• 提取重複邏輯為私有方法；清理未使用 import 與區域變數。
• 常數定義順序：public/protected/private static final Type NAME。
• 實作 Serializable 的類必須顯式定義 serialVersionUID。

七、可讀性與效能

• 複雜三元運算改寫為 if-else。
• 日誌物件定義為 private static final，避免重複初始化開銷。
• 禁用 System.out.println，僅啟動/關閉階段允許，其餘全用日誌框架。

八、圈複雜度控制

• 類 ≤500 行；方法 ≤30 行；巢狀深度 ≤5；調用深度 ≤15；參數 ≤7。

九、SQL 規範與優化

格式與註解

• 關鍵字、運算符、逗號前後加空格；複雜 SQL 單行註解置前；業務邏輯盡量移出 SQL。

優化核心原則

1. 統一 SQL 寫法避免重複解析；多表連接用別名，建議 ≤5 表。
2. 禁用 SELECT *；WHERE 條件用參數變量而非常數。
3. 少用嵌套查詢，NOT IN 改 NOT EXISTS；用 JOIN 替代 EXISTS。
4. UNION ALL 優於 UNION（去重開銷大）。
5. IN/OR 可能導致全表掃描，若無大量重複值可拆分並確保含索引列。
6. 大量排序影響效能，減少 ORDER BY/GROUP BY；排序列建立索引，非唯一用 UNION ALL。
7. 複合索引必須用到主鍵列；索引列避免 NULL、!=；查詢/排序列順序與索引一致。
8. 列運算（函數、表達式）導致全表掃描，將操作移至等號右側。

結語

代碼審查非一次性動作，需持續融入 CI/CD 與團隊文化。建議將核心規則配置為 Checkstyle/SpotBugs/SonarQube 規則集，實現自動化攔截，讓品質可見、可控、可持續。