Java 編程規範精華 (三)：存取函數、局部變量、參數、類與包命名標準

Java 編程規範精華 (三)：存取函數、局部變量、參數、類與包命名標準

本文節選自經典《Java 編程規範》核心章節，聚焦集合存取函數設計、多字段原子訪問、存取函數可見性、靜態字段初始化、局部變量/參數命名與注釋、類/介面/包/編譯單元組織標準，為團隊代碼風格統一、代碼審查、重構治理提供權威參考。

一、集合存取函數設計模式

集合 (List/Set/Map/陣列) 比單值字段複雜，需提供粒度化操作而非暴露整個集合引用，以封裝內部結構、支援未來遷移 (如 ArrayList → LinkedList、引入 B 樹)。

// 標準實現範例
public class Order {
    private final List items = new ArrayList<>();
    
    // 唯讀視圖，防止外部直接修改繞過邏輯
    public List getOrderItems() {
        return Collections.unmodifiableList(items);
    }
    
    public void setOrderItems(List newItems) {
        items.clear();
        if (newItems != null) items.addAll(newItems);
    }
    
    public void addOrderItem(OrderItem item) {
        if (item == null) throw new IllegalArgumentException("Item cannot be null");
        items.add(item);
        item.setOrder(this); // 維護雙向關聯
    }
    
    public void removeOrderItem(OrderItem item) {
        items.remove(item);
        item.setOrder(null);
    }
    
    public OrderItem newOrderItem(String productId, int quantity) {
        OrderItem item = new OrderItem();
        item.setProductId(productId);
        item.setQuantity(quantity);
        addOrderItem(item);
        return item;
    }
}

二、多字段原子訪問與不變量保護

當多字段構成不變量 (如 x/y 坐標必須同時變更、訂單總額 = 明細之和) 時，禁止提供單獨 setter，改為原子更新方法。

public class Shape {
    private float x, y;
    private float width, height;
    private BigDecimal orderTotal;
    private List items;
    
    // 正確：原子移動，保證坐標一致性
    public void move(float dx, float dy) {
        this.x += dx;
        this.y += dy;
    }
    
    // 錯誤：單獨 setter 破壞不變量
    // public void setX(float x) { this.x = x; } // 禁止！
    
    // 內部協作方法：package-private，供 move() 調用
    void setPosition(float x, float y) { // 僅內部/同包可見
        this.x = x; this.y = y;
    }
    
    // 訂單總額：僅由項目操作方法維護，不提供 setter
    public BigDecimal getOrderTotal() { return orderTotal; }
    // private void setOrderTotal(BigDecimal t) { this.orderTotal = t; } // 私有
    
    public void addItem(OrderItem item) {
        items.add(item);
        recalcTotal(); // 原子更新總額
    }
}

三、存取函數可見性決策矩陣

四、靜態字段必須顯式初始化

規則：靜態字段 (類字段) 必須被賦予有效初值，不能假設實例創建前已被初始化。

public class Config {
    // 正確：靜態初始化塊/聲明處賦值
    private static final String DEFAULT_ENCODING = "UTF-8";
    private static final Map CACHE = new ConcurrentHashMap<>();
    
    static {
        // 複雜初始化邏輯
        CACHE.put("key", loadFromDb());
    }
    
    // 錯誤：依賴實例建構子初始化靜態字段
    // public Config() { if (CACHE.isEmpty()) init(); } // 多線程不安全、時序不可控
}

五、局部變量命名與聲明規範

1. 命名約定

• 通用：完整英文描述符，駝峰式 customerList、maxRetryCount
• 流：in/out/inOut (單一輸入輸出) 或 inputStream/outputStream/ioStream
• 迴圈計數器：i/j/k (傳統、廣泛接受) 或 loopCounter/index
• 異常對象：e/ex/exception

2. 聲明與注釋鐵律

1. 一行聲明一個變量：便於行末注釋、版本控制差異對比
2. 行末注釋說明用途：int retryCount = 0; // 重試次數計數器
3. 變量專用：一個變量只幹一件事，嚴禁復用 (如先用作計數器、後用作索引)，降低認知負荷、防止殘留值 Bug
4. 就近聲明：在首次使用前聲明，縮小作用域；或統一在方法開頭聲明 (團隊統一風格)

六、方法參數標準

1. 命名風格

• 遵循局部變量命名：customer、inventoryItem
• 推薦前綴「a/an」：aCustomer、anInputStream、anException —— 區分參數與字段/局部變量，避免名稱遮蔽

2. Javadoc @param 註解三要素

/**
 * 根據用戶 ID 查詢訂單
 * @param userId 用戶唯一標識，必須 > 0
 * @param pageNum 頁碼，從 1 開始，預設 1
 * @param pageSize 每頁條數，範圍 [1, 100]，預設 20
 * @return 訂單分頁結果，非 null
 * @throws BizException USER_NOT_FOUND 當用戶不存在
 */
public Page findOrders(@Valid @Min(1) Long userId, 
                              @Min(1) @Max(100) Integer pageSize) { ... }

3. 參數類型傾向介面

• 優先使用介面類型：List 而非 ArrayList、Map 而非 HashMap、Runnable 而非 Thread
• 好處：多態解耦、測試易 Mock、實現可替換 (LinkedList、TreeMap...)

七、類、介面、包、編譯單元組織標準

1. 類命名

• 完整英文描述符，每詞首字母大寫 (PascalCase)：Customer、OrderItem、FileStream
• 單數形式 (集合類用複數：Collections、Arrays)
• 異常類以 Exception 結尾：BizException
• 工具類以 Utils/Helper 結尾：StringUtils

2. 類文檔註解 (Javadoc 類級)

/**
 * 訂單領域實體，封裝訂單生命週期、狀態機、金額計算等核心業務規則。
 * 

 * 設計意圖：作為聚合根，保證訂單明細、總額、狀態的一致性。
 * 線程安全：非線程安全，需外部同步或單線程訪問。
 * 已知限制：不支援分佈式事務，跨服務操作需引入 Saga 模式。
 * 
 * @author Zhang San
 * @version 2.1.0
 * @since 1.0.0
 * @see OrderItem
 * @see OrderStatus
 */
public class Order { ... }

3. 類成員聲明順序

1. 靜態常量 (public static final)
2. 靜態字段 (private static)
3. 實例字段 (private)
4. 建構子 (public → protected → private)
5. 靜態工廠方法
6. 公共實例方法
7. 保護實例方法
8. 私有實例方法
9. 內部類/介面/枚舉/記錄

組內按字母序排序，或靜態方法優先、實例方法次之，團隊統一即可。

4. 介面設計規範

• 命名同類 (PascalCase)，常用形容詞尾綴：Runnable、Serializable、Comparable、PaymentService
• 常量定義：int MAX_SIZE = 100; (隱式 public static final)
• 擴充：interface Sub extends Super1, Super2 { }
• 實現類命名：接口名 + Impl (如 UserServiceImpl) 或特徵前綴：JdbcUserRepository

5. 包命名與結構

• 全小寫、點分隔、反向域名：com.company.project.module
• 分層包結構：controller、service、repository、domain、dto、config、exception、util
• 包私有類：package-private class 封裝模組內部實現

6. 編譯單元 (源文件) 結構

1. 包聲明
2. 導入語句 (按字母序、分組：java → javax → 第三方 → 內部)
3. 類/介面定義 (每文件一個 public 類，文件名 = 類名)

八、總結

規範的本質是降低認知負荷、減少溝通成本、防範潛在缺陷。集合存取函數封裝結構變更、多字段原子操作守護不變量、存取函數可見性最小化、靜態字段確定性初始化、局部變量專用且自註解、參數介面化解耦、類/包命名語義化分層——這些看似瑣碎的細節，累積起來決定了代碼庫的可讀性、可維護性、可演進性。團隊應建立 checkstyle.xml、spotbugs、SonarQube 自動化檢查，將規範內化為工程基因。