您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Java 開發編碼規範：從命名到架構的工程化實踐

編輯：Java 相關知識

規範的核心價值

統一編碼風格不是為了「好看」，而是為了：

降低認知負荷：代碼像同一人所寫，閱讀無需切換上下文
減少人員流動成本：新成員無需適應多種風格
啟用自動化工具：統一風格才能跑檢查、格式化、重構

原則：可讀性優於個人偏好，團隊共識大於個人堅持。

命名規範：一眼看懂意圖

包名：全小寫、單數、反域名

com.company.project.module  // 標準
com.company.project.utils   // 避免 utils、common 等無意義包名

類/介面：PascalCase，名詞或形容詞

UserService, OrderController, Serializable, Runnable

方法/變量/參數：camelCase，動詞或名詞短語

calculateTotal(), userName, pageSize, MAX_CONNECTIONS

常量：全大寫下劃線分隔

static final int DEFAULT_TIMEOUT = 3000;
static final String CONFIG_FILE = "application.yml";

數組聲明：括號貼類型

byte[] buffer;   // 正確：強調「byte 數組」類型
// byte buffer[]; // 避免：C 風格殘留

源文件結構：標準化佈局

1. 版權/許可證頭註釋
2. package 語句
3. import 語句（標準庫 → 第三方 → 本地，字母序）
4. 類/介面文檔註釋（Javadoc）
5. 類/介面定義
6. 字段（常量 → 靜態 → 實例，public → protected → private）
7. 構造器（參數少 → 多）
8. 方法（公共 → 私有，邏輯相關分組）
9. 內部類/枚舉
10. main 方法（若有，置底）

代碼格式化：機器強制統一

縮進：2 空格，**禁用 Tab**（跨編輯器顯示差異大）
行寬：120 字符（現代寬屏下 80 過窄）
大括號：K&R 風格（左大括號不換行，右大括號獨佔行）
空格：關鍵字後、運算符兩側、逗號後加空格；括號內不加
空行：邏輯塊之間、方法之間、字段組之間

// 推薦風格
public void doSomething(int param) {
    if (param > 0) {
        List list = new ArrayList<>();
        for (String item : list) {
            process(item);
        }
    }
}

文檔註釋：Javadoc 為準

所有 public/protected 類、方法、字段**必須**寫 Javadoc
使用 @param、@return、@throws、@see 標籤
避免 @author（代碼屬於團隊，非個人）
複雜邏輯加行內註釋（//），解釋「為什麼」而非「做什麼」

核心編程實踐

資源管理：try-with-resources 強制關閉

// Java 7+ 標準寫法
try (FileOutputStream fos = new FileOutputStream(file)) {
    project.save(fos, "IDE Project File");
} // 自動關閉，即使拋異常

字符串拼接：StringBuilder 替代 +

// 循環/多次拼接
StringBuilder sb = new StringBuilder();
for (String part : parts) {
    sb.append(part).append(',');
}
String result = sb.toString();

同步最小化：縮小鎖範圍

// 避免：整個方法同步
public synchronized void update() { ... }

// 推薦：僅同步臨界區
public void update() {
    // 非臨界操作...
    synchronized (lock) {
        // 核心狀態修改
    }
}

異常處理：具體捕獲、拋出豐富異常

捕獲具體異常類，禁用 catch (Exception e)
自定義異常攜帶上下文信息（ID、狀態碼）
業務異常用檢查型異常，系統異常用非檢查型

不可變性優先：final、不可變集合、防禦性複製

public final class Order {
    private final List items;
    public Order(List items) {
        this.items = Collections.unmodifiableList(new ArrayList<>(items)); // 防禦性複製+不可變視圖
    }
}