Java 編碼規範全套標準：命名、文件結構、文檔註釋最佳實踐

命名規範

源文件結構順序

1. 版權/許可證聲明（塊註釋）
2. Package 語句
3. Import 語句：標準庫 → 第三方 → 本地，按字母序，通配符僅用於同包多類
4. 類/接口文檔註釋（Javadoc）
5. 類聲明：public class X extends Y implements Z，extends/implements 換行
6. 靜態常量
7. 實例字段
8. 構造器（參數少→多）
9. 公共方法
10. 受保護/包私有方法
11. 私有方法
12. 內部類/枚舉/記錄
13. toString()、equals()/hashCode()、clone() 等通用方法

關鍵代碼風格細節

• 大括號：K&R 風格（行尾 `{`），控制語句必加大括號哪怕單行。
• 縮進：4 空格，禁用 Tab。
• 行長：建議 120 字符，換行按運算符優先級、參數分組。
• 空行：邏輯塊之間、方法之間、字段組之間各留一空行。
• Javadoc：所有 public/protected 類、方法、字段必寫；@param、@return、@throws、@see 齊全。

方法簽名規範

/**
 * 根據 ID 查詢用戶
 * @param id 用戶主鍵，必須 > 0
 * @return 用戶對象，不存在返回 null
 * @throws IllegalArgumentException id <= 0
 * @throws DataAccessException 數據庫訪問異常
 */
public User findById(long id) throws DataAccessException {
    if (id <= 0) throw new IllegalArgumentException("id must > 0");
    // ...
}

構造器重載順序

public class User {
    public User() { this(0, null); }
    public User(long id) { this(id, null); }
    public User(long id, String name) {
        this.id = id;
        this.name = name;
    }
}

Clone 方法標準實現

@Override
public User clone() {
    try {
        User cloned = (User) super.clone();
        // 深拷貝可變字段
        cloned.tags = new ArrayList<>(this.tags);
        return cloned;
    } catch (CloneNotSupportedException e) {
        throw new AssertionError("實現 Cloneable 不可能拋出此異常", e);
    }
}

toString 規範

使用 Objects.toStringHelper(this) (Guava) 或手寫格式：User{id=1, name='张三'}，包含所有關鍵字段，便於日誌診斷。

工具落地

• IDE 導入統一 codestyle.xml（IntelliJ）或 formatter.xml（Eclipse）。
• Maven 引入 maven-checkstyle-plugin、spotbugs-maven-plugin、pmd-maven-plugin 做 CI 門禁。
• Git pre-commit hook 執行格式化與靜態檢查。