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

Java 程式碼撰寫規範與最佳實務指南

編輯：Java 相關知識

前言

統一的程式碼風格能顯著提升團隊協作效率、降低維護成本、減少認知負擔。本文整理業界通用的 Java 程式碼規範，涵蓋命名慣例、檔案結構、格式化、程式設計技巧、效能與可攜性等面向，供專案團隊參考落地。

一、命名規範

元素	規則	範例
Package	全小寫，單字或縮寫	`com.company.project.module`
Class / Interface	PascalCase，名詞	`UserService`, `Serializable`
Method	camelCase，動詞開頭	`getUserById()`, `calculateTotal()`
Variable / Parameter	camelCase，名詞	`userName`, `maxRetryCount`
Constant (static final)	UPPER_SNAKE_CASE	`DEFAULT_TIMEOUT_MS`
Array	`type[] variableName`	`byte[] buffer;` (非 `byte buffer[];`)

參數命名建議：與對應欄位同名，配合 this.field = field 明確語意。

二、Java 檔案結構順序

版權/授權宣告：檔案最頂端
Package 宣告
Import 區塊：標準庫 → 第三方 → 專案內部，字母序；同包群組用 *
類別/介面 Javadoc：說明用途、執行緒安全性、使用範例
類別宣告：public class Name extends Base implements Interface
常數欄位 (static final)
實例欄位：依 public → protected → package-private → private 排序
建構子：參數少 → 多
公開方法
受保護/包私有方法
私有方法
內部類別/枚舉
toString()：每個類別必須實作
main()：放置檔案末尾（若有）

三、格式化規範

縮排：2 空格，**禁止 Tab 字元** (IDE 設定 Tab→Spaces)
行寬：120 字元 (現代螢幕建議放寬至 120，傳統 80)
換行原則：在運算子、逗號後換行；續行再縮排 2 空格
大括號：if (cond) { 同行開頭，} 獨立一行並對齊對應 {
空白：關鍵字後加空格 if (cond)；方法呼叫無空格 method(arg)；運算子前後各一空格
單行區塊：簡單存取子可單行 public int getId() { return id; }，邏輯區塊禁止單行

四、程式設計核心規範

1. 例外處理

拋出具體異常，避免 throw new Exception() 或 throw new RuntimeException() 無語意
main() 或執行緒進入點統一捕獲並記錄完整堆疊

資源釋放使用 try-with-resources (JDK 7+)：

try (FileOutputStream fos = new FileOutputStream(file)) {
    project.save(fos);
} // 自動 close()

2. 物件建構與 Clone

實作 Cloneable 並覆寫 clone() 深拷貝可變欄位
除非框架強制，**避免將類別標記為 final**；改用 Javadoc 標註 @apiNote Not designed for extension
欄位預設 private，必要時 protected 供子類存取

3. 字串處理效能

迴路拼接**必須使用 StringBuilder** (單執行緒) 或 StringBuffer (多執行緒)
避免 String s += "x" 產生大量暫存物件

4. 同步化原則

縮小同步範圍，僅鎖定必要區塊
避免在同步區塊呼叫外部方法（死鎖風險）
優先使用 java.util.concurrent 高階併發工具 (ConcurrentHashMap, AtomicInteger, Lock 等)

5. 列舉模式 (JDK 5+ 原生 `enum`)

public enum Color {
    BLACK(0, 0, 0), RED(255, 0, 0), GREEN(0, 255, 0), BLUE(0, 0, 255), WHITE(255, 255, 255);
    private final int r, g, b;
    Color(int r, int g, int b) { this.r = r; this.g = g; this.b = b; }
    public int getRGB() { return (r << 16) | (g << 8) | b; }
}

原生 enum 提供型別安全、單例保證、可實作介面、支援 switch，完美替代舊有 static final 常數模擬法。