四大有害 Java 編碼習慣：根治代碼可讀性與維護性殺手

代碼是給人讀的，順便能在機器上跑。許多看似微不足道的編碼習慣，實則是可讀性與維護性的隱形殺手。本文揭露四大高頻陋習，提供具體改進方案，助你編寫自文檔化、低認知負荷的優雅代碼。

習慣一：變量命名不區分作用域——認知負荷製造機

現狀：局部變量、方法參數、實例字段混用同一命名風格（如均用 camelCase），閱讀者須反覆上下文切換才能判斷變量屬性。

反例：

public boolean equals(Object arg) {
    if (!(arg instanceof Range)) return false;
    Range other = (Range) arg;
    return start.equals(other.start) && end.equals(other.end); // start/end 是字段？局部？參數？
}

改進：引入語義前綴區分作用域

• 參數：a 前綴（argument） → aOther
• 字段：f 前綴（field） → fStart、fEnd
• 局部變量：無前綴 → other

public boolean equals(Object aOther) {
    if (!(aOther instanceof Range)) return false;
    Range other = (Range) aOther;
    return fStart.equals(other.fStart) && fEnd.equals(other.fEnd);
}

核心價值：一眼識別變量生命週期與可見性，消除「這是字段還是局部？」的心智切換成本。這非匈牙利標記法（編碼類型），而是編碼作用域語義，現代 IDE 顏色區分無法完全替代（代碼評審、Git diff、紙面閱讀場景）。

習慣二：按技術層分包而非業務特性分包——模塊化假象

現狀：com.app.action、com.app.dao、com.app.model、com.app.util。同一業務特性的類被拆散到多個包，導致：

• 類被迫 public，破壞封裝，package-private 失效。
• 違反「高內聚、低耦合」，修改一特性需跳轉多包。
• 無法進化式重構，包結構僵化。

改進：按業務特性/領域分包

com.app.painting   // Painting、PaintingDAO、PaintingAction、statements.sql、view.jsp
com.app.auction
com.app.useraccess
com.app.util       // 真正通用的基礎設施代碼

收益：

• 高內聚：特性相關所有文件（Java、SQL、JSP、配置）共聚一包。
• 自描述：包名即業務目錄，新人秒懂系統功能分佈。
• 封裝友好：默認 package-private，僅暴露必要 API。
• 易重構：刪除特性 = 刪除目錄；拆分特性 = 拆分包，支持演化式架構。
• 定位快：編輯相關代碼無需跨包跳轉。

誤區澄清：分層架構不等於包結構分層。架構分層通過依賴規則（如 Controller 依賴 Service，Service 依賴 Repository）約束，而非物理包隔離。ArchUnit 等工具可自動驗證架構規則。

習慣三：濫用 JavaBean 而非不可變對象——可變狀態的溫床

現狀：習慣性為數據載體生成無參構造器 + 全套 Getter/Setter，即使對象邏輯上應不可變（如訂單 ID、金額、創建時間）。

不可變對象優勢：

• 線程安全無需同步，天然適用併發環境。
• 構造時驗證，確保對象始終處於合法狀態。
• 可安全共享、緩存、作為 Map Key/Set 元素。
• 消除「意外修改」整類 Bug，降低心智負荷。

改進方案：

• 領域模型優先用 record、Lombok @Value、手寫不可變類（final 字段、無 Setter、構造器驗證、防御性拷貝集合）。
• JavaBean 僅用於框架強制要求場景（如 JPA 實體、表單綁定、序列化 DTO），並儘量隔離在邊界層。
• 構建器模式應對複雜構造需求。

Bloch 語錄：「除非有充分理由使類可變，否則應使其不可變。」

習慣四：私有成員前置——倒置的閱讀體驗

現狀：類文件開頭堆砌私有字段、構造器、私有方法，公共 API 埋在文件末尾。閱讀者必須穿越實現細節才能看到「這個類能做什麼」。

認知科學依據：人類理解遵循「由抽象到具體、由接口到實現」的自上而下過程。先見公共契約，建立心智模型，再按需深入實現細節。

改進：遵循 Javadoc/IDE 大綱順序組織類結構

1. 公共構造器/工廠方法
2. 公共實例方法（核心業務 API）
3. 受保護方法（擴展點）
4. 私有方法（實現細節）
5. 私有字段/內部類

歷史佐證：C++ 社區早已修正此規範（Google C++ Style Guide、ISO C++ Core Guidelines 均要求 public 先行）。Java 早期慣例受 C 結構體影響，現應主動糾偏。

工具輔助：IntelliJ IDEA Code > Rearrange Code、Save Actions 插件可自動按規則排序成員。

總結

良好習慣非約束，而是解放。消除命名歧義、重塑包結構、擁抱不可變性、正確組織類結構，四大改動讓代碼自我解釋、易於導航、安全併發、愉悅閱讀。從今天的提交開始，做代碼閱讀者的貼心人。