Java 程式碼規範與最佳實踐：寫出可維護、專業級的代碼

為什麼需要程式碼規範？

「代碼是給人看的，順便能在機器上跑。」統一的程式碼風格能：

• 降低認知負荷：團隊成員專注業務邏輯，而非解讀格式差異。
• 減少合併衝突：統一縮排、大括號位置、import 排序，Git diff 更乾淨。
• 啟用靜態分析：Checkstyle / SpotBugs / PMD / SonarQube 自動掃描，CI 流水線攔截低級錯誤。
• 傳遞專業度：規範的代碼是工程師素養的名片，利於 Code Review 與知識傳承。

命名規範：好名字勝過千言萬語

原始碼檔案結構

// 1. 版權/授權標頭 (公司/專案統一模板)
/**
 * Copyright © 2024 Company Name. All rights reserved.
 */

// 2. Package 宣告
package com.company.project.module;

// 3. Import 區塊：標準庫 → 第三方 → 本地，字母序，避免 *
import java.time.LocalDateTime;
import java.util.List;
import com.fasterxml.jackson.annotation.JsonProperty;
import com.company.project.common.BaseEntity;

// 4. 類別/介面定義 (含 Javadoc)
/**
 * 訂單領域實體，包含狀態機流轉邏輯。
 * @author Developer Name
 * @since 1.0.0
 */
public class Order extends BaseEntity {
    // 靜態常量
    // 實例欄位
    // 建構子
    // 公共方法
    // 保護/私有方法
    // 內部類/Enum/Record
}

格式化鐵律 (配合 IDE 自動格式化)

• 縮排：4 空格 (禁用 Tab)，延續縮排 8 空格。
• 大括號：K&R 風格 (行末左大括號)，if/else/for/while 單行也要加大括號。
• 行寬：120 字元 (現代寬螢幕標準)，參數過多換行對齊。
• 空行：邏輯區塊間空一行，方法之間空一行，類內首尾不空行。
• 運算子：二元運算子前後各一空格，一元運算子緊貼運算元。

核心編程原則

1. 清晰表達意圖

// 差：魔術數字、縮寫
if (status == 2) { ... }

// 好：常量、語義化
if (order.getStatus() == OrderStatus.PAID) { ... }

2. 單一職責、小方法、小類

• 方法 ≤ 30 行，圈複雜度 ≤ 10，參數 ≤ 4 (超過用 Parameter Object/Builder)。

3. 避免空指針：Optional、空物件模式、契約式設計

// 回傳 Optional 強制調用者處理缺失情況
public Optional findById(Long id) { ... }

// 參數驗證前置
public void update(@NonNull User user) {
    Objects.requireNonNull(user, "User must not be null");
    ...
}

4. 併發安全：不可變物件、執行緒封閉、同步工具類

• 優先用 final、Immutable (Guava/Immutables)、ThreadLocal、ConcurrentHashMap、LongAdder。

5. 異常處理：具體化、文檔化、不吞沒

// 定義業務異常
public class InsufficientBalanceException extends BusinessException { ... }

// 拋出帶上下文
throw new InsufficientBalanceException("Account " + accountId + " balance " + balance + " < " + amount);

// 全域異常處理器統一轉碼、記錄、回應

自動化落地：從規範到習慣

1. IDE 設定：導入團隊統一的 codeStyle.xml (IntelliJ) / formatter.xml (Eclipse)，啟用 Save Actions (格式化、整理 Import、加最終修飾符)。
2. Git Hooks：pre-commit 跑 Checkstyle/SpotBugs，commit-msg 驗證訊息格式 (Conventional Commits)。
3. CI 流水線：SonarQube Quality Gate (覆蓋率 ≥ 80%、重複率 ≤ 3%、零 Blocker/Critical)。
4. Code Review 清單：命名、異常、測試、效能、安全、文檔同步。