Java 編程常見錯誤匯總與最佳實踐指南

前言

靜態分析工具（如 Checkstyle、PMD、SpotBugs）能捕獲語法層面問題，但設計層面的「代碼氣味」需人工識別。本文匯總 OOP 設計、命名、異常、縮進、常量、測試六大維度的典型錯誤與修正方案。

1. 類命名：拒絕「管理者」後綴

2. 方法命名：語義優於慣例

• 有返回值：boolean isValid(String name)、String content()、int ageOf(File file) —— 無 get 前綴。
• 無返回值：void save(File file)、void process(Work work) —— 動詞開頭描述動作。
• 測試方法：void returnsContentInUnicode() —— Javadoc 首句 HttpRequest can return its content in Unicode.，方法名為無主語句子。

3. 變量命名：極簡且無歧義

• 集合用復數：List<String> names
• 單一實體用類名小寫：File file、User user
• 基本類型禁用類名：❌ Integer number → ✅ int age
• 構造器參數衝突：去元音縮寫 String rcpt 對應 this.recipient
• 一次性變量內聯：❌ String name = "data.txt"; return new File(name); → ✅ return new File("data.txt");

4. 構造器：單一主構造器 + 鏈式調用

public class Server {
    private final String address;
    // 主構造器
    public Server(String uri) { this.address = uri; }
    // 便利構造器委託主構造器
    public Server(URI uri) { this(uri.toString()); }
}

5. 異常處理：快速失敗，不吞噬

• ❌ 用異常控制流程：try { size = fileSize(); } catch { size = 0; } —— 掩蓋真實錯誤（如磁盤滿）。
• ✅ 受檢異常向上拋出：public void save() throws IOException。
• ✅ 多調用合併一個 try-catch 塊，減少棧幀開銷。

6. 縮進與格式：80 字符硬限制

// ✅ 正確：左括號行尾，參數對齊
StringUtils.join(
    Arrays.asList(
        "first line", "second line",
        StringUtils.join(Arrays.asList("a", "b"))
    ),
    "separator"
);

7. 常量濫用：業務常量 vs 魔法值替身

class Document {
    // ❌ 替換字面量無業務意義
    private static final String D_LETTER = "D";

    // ✅ 業務常量：擴展名、狀態碼
    private static final String EXTENSION = ".doc";
    private static final int MAX_RETRY = 3;
}

• 測試代碼禁止共享常量：每個測試方法獨立構造數據，避免耦合。

8. 測試數據耦合：變量隔離

// ❌ 字面量耦合
User user = new User("Jeff");
assertThat(user.name(), equalTo("Jeff"));

// ✅ 變量隔離
String name = "Jeff";
User user = new User(name);
assertThat(user.name(), equalTo(name));

總結檢查清單

1. 類名是否為領域名詞？
2. 方法名是否描述「做什麼」或「返回什麼」？
3. 變量名是否最短無歧義？
4. 構造器是否單一入口？
5. 異常是否向上拋出而非吞噬？
6. 縮進是否 ≤ 80 字符？
7. 常量是否有業務語義？
8. 測試數據是否相互隔離？