Java 代碼規範完整指南：命名、格式、方法設計與 JSP 規範

統一代碼風格可顯著降低認知負荷、減少缺陷、提升團隊協作效率。本文整理涵蓋命名規約、格式規範、方法設計原則、JSP 規範的企業級 Java 代碼標準，可直接作為團隊《編碼規範》基線。

一、命名規範

1.1 包名

• 全小寫，單數形式，反向域名：com.company.module.submodule
• 避免使用關鍵字、保留字

1.2 類/介面/枚舉/註解

• PascalCase：UserService、OrderStatus、@Transactional
• 名詞或名詞短語，介面可用形容詞：Serializable、Runnable
• 測試類：UserServiceTest、UserServiceIT (整合測試)

1.3 方法/變數/參數

• camelCase：getUserById、userName、pageSize
• 布林型：is/has/can/should 開頭：isActive、hasPermission
• 常量：UPPER_SNAKE_CASE：MAX_UPLOAD_SIZE、DEFAULT_PAGE_SIZE
• 避免單字母變數 (除循環計數器 i/j/k)

1.4 陣列宣告

// 推薦
String[] names;
int[] scores;

// 不推薦
String names[];
int scores[];

1.5 成員變數區分

• 非公有實例變數：private String userName; (無前綴，靠 this. 區分)
• 靜態常量：private static final int MAX_SIZE = 100;
• 建議：this.field 明確區分實例變數與參數/局部變數

二、格式規範

2.1 編碼與換行

• 檔案編碼：UTF-8 (無 BOM)
• 換行符：LF (Unix)，禁止 CRLF
• IDE 統一配置：EditorConfig / .gitattributes

2.2 縮排與大括號

• 縮排：**4 空格**，禁用 Tab
• 大括號 不換行 (K&R 風格)：

if (condition) {
    doSomething();
} else {
    doOther();
}

try {
    risky();
} catch (Exception e) {
    handle(e);
} finally {
    cleanup();
}

2.3 空格規則

• 關鍵字後加空格：if (x > 0)、for (int i = 0; i < n; i++)
• 運算符兩側空格：a = b + c、flag ? val1 : val2
• 方法宣告：void method(String param) { (左括號前空格)
• 調用無空格：method(arg)、array[index]
• 禁止無意義括號：if (x == 42) 而非 if ((x) == 42)

2.4 註釋規範

• 類檔案頭部：版權、作者、版本、模組說明
• 公開方法：@param、@return、@throws、@see 完整
• 複雜邏輯：行內註釋說明「為什麼」，而非「做什麼」

三、方法設計原則

3.1 核心指標

• 行數：≤ 80 行 (含註釋)，超過即拆分
• 參數：≤ 4 個，超過封裝為參數對象/Builder
• 圈複雜度：≤ 10，超過重構
• 單一職責：一個方法只做一件事，名稱精準表達意圖

3.2 契約式設計

• 前置條件：參數驗證 (Objects.requireNonNull、Preconditions.checkArgument)
• 後置條件：返回值明確、異常類型精準
• 不變量：文檖說明線程安全性、冪等性、副作用

3.3 禁止模式

• 無意義動詞：process()、handle()、doIt()
• 布林陷阱：boolean flag 控制雙分支 → 拆分為兩方法
• 過度遞歸：尾遞歸優化不可靠，改迭代或显式棧
• 全域狀態依賴：難測試、難並發，改依賴注入

3.4 可重入與線程安全

• 無狀態優先：方法不依賴實例/靜態可變狀態
• 若需共享狀態：synchronized、Lock、Atomic*、ThreadLocal 明確同步策略

四、JSP 規範 (歷史專案維護參考)

• 目錄：kebab-case 單詞 user-management
• 檔名：PascalCase UserList.jsp、UserAddAction.jsp
• 參數名：camelCase userId、pageNo
• 功能命名約定：
  • 列表/首頁：XxxIndex.jsp
  • 新增頁/處理：XxxAdd.jsp / XxxAddAction.jsp
  • 修改頁/處理：XxxModify.jsp / XxxModifyAction.jsp
  • 刪除處理：XxxDelAction.jsp
• 現代專案建議：Thymeleaf/FreeMarker + Spring MVC / REST API + 前端分離

五、工具化落地

1. Checkstyle：google_checks.xml 或 sun_checks.xml 為基線定製
2. SpotBugs / PMD：靜態缺陷檢測
3. EditorConfig：跨 IDE 格式統一
4. Git Hooks：pre-commit 跑格式檢查，pre-push 跑測試
5. CI 管道：合併請求強制通過所有檢查

總結

代碼規範不是束縛，而是團隊共識的外化。好規範讓正確的事變容易，錯誤的事變困難。建議：起步採用成熟標準 (Google Java Style / Alibaba Java 開發手冊)，結合團隊實況微調，工具化強制執行，定期複盤優化。代碼是給人讀的，順便給機器執行。