Effective Java Item25：將原始碼檔案限制為單一top-level的類別

整理 Effective Java 書中 Item 25：Limit source files to a single top-level class 心得筆記

主旨：保持一檔一類別，避免隱藏的地雷

Java 技術上允許你在一個 .java 檔案中定義多個 top-level 類別（也就是非巢狀的 public 或 package-private 類別），但這麼做其實是一個踩雷設計。這會讓你的程式行為變得難以預測，尤其當你在不同檔案中定義了相同名稱的類別，編譯結果會依照檔案的編譯順序而不同，產生極大的風險。

點出問題：同名類別混在一起，行為跟著變

想像你寫了一個主程式如下：

public class Main {
    public static void main(String[] args) {
        System.out.println(Utensil.NAME + Dessert.NAME);
    }
}

接著你在 Utensil.java 中放了兩個 top-level 類別：

// Utensil.java
class Utensil {
    static final String NAME = "pan";
}

class Dessert {
    static final String NAME = "cake";
}

主程式會印出 pancake，沒問題。但如果你後來又加了一個 Dessert.java 檔，內容是：

// Dessert.java
class Utensil {
    static final String NAME = "pot";
}

class Dessert {
    static final String NAME = "pie";
}

這時候你用不同的編譯順序執行，就會發現結果不一樣：

javac Main.java              # 印出 pancake
javac Dessert.java Main.java # 印出 potpie

這種結果完全取決於編譯順序，超級危險，難以除錯。

範例：正確的寫法應如何設計？

最簡單的修正方式是把 Utensil 和 Dessert 拆成不同的檔案。另一種更常見的做法，是把這些「輔助用的小類別」定義為 static 的巢狀類別：

public class Test {
    public static void main(String[] args) {
        System.out.println(Utensil.NAME + Dessert.NAME);
    }

    private static class Utensil {
        static final String NAME = "pan";
    }

    private static class Dessert {
        static final String NAME = "cake";
    }
}

這樣一來，不但能讓程式碼集中管理，也不會引發任何多重定義或命名衝突的問題。

大型專案裡的踩雷經驗

曾有開發者在多人合作的專案中，為了偷懶把三個 utility 類別都塞在同一個檔案裡，結果某人複製其中一段到另一個檔案時沒發現名稱重複，導致某些功能偶爾出錯。找了兩天才發現問題根源就是編譯器載入的是不同版本的類別定義。這種錯誤在 Git merge 或 refactor 時很容易出現，卻非常難以追蹤。

小結：堅守一檔一類別，就是防止災難的開始

雖然語法允許，但千萬不要在同一個 Java 檔案中定義多個 top-level 類別。這樣會：

• 造成多重定義問題
• 讓編譯結果不穩定
• 增加維護與除錯困難
• 在大型團隊合作下容易出包

如果真的需要多個邏輯相關的類別，請改用 static member class 或移到各自獨立的檔案中。遵守這個原則，不只是為了風格，更是避免未來掉進難解的 bug 黑洞。