Java 編碼規範進階標準：命名、格式、註釋與文件結構全指南

前言

統一的編碼規範是團隊協作、代碼維護與質量保障的基石。本文整理自某郵政系統 Java 開發標準，涵蓋命名約定、排版格式、註釋要求、文件結構四大維度，提供落地可執行的細則，供團隊參考定制。

一、 命名規範

1. 通用原則

• 全英文描述，禁用拼音/無關詞；包名全小寫，類/接口首字母大寫（PascalCase），方法/變量駝峰式。
• 慎用縮寫，若用須為公認慣例（如 impl、mgr），長度 ≤ 25 字符。
• 常量全大寫下劃線分隔（MAX_COUNT）；避免魔法數字，提煉為常量。

2. 專項命名規則

二、 排版格式

• 縮進：4 空格；大括號單獨佔行，與前行對齊。
• 空格：關鍵字/運算符前後各一空格；單目運算符貼近操作數；逗號後空格。
• 對齊：相關變量聲明、參數列表按類型/名稱對齊；行長不超過屏幕寬度，換行優先在逗號/運算符處。
• 空行：邏輯塊間單空行；類內「四個 P」（屬性、構造器、方法、內部類）間至少一空行；避免連續多空行。

三、 註釋規範

• 文件頭：包含標題、描述、版權、公司、作者、版本，放在 package/import 後、class 前。
• 類/接口：說明職責、設計意圖、觀察者模式等關鍵決策。
• 方法：每個公共方法必須有 Javadoc，含功能、參數、返回值、異常、算法、副作用、硬件依賴。
• 行內：複雜邏輯、非明顯處理、Hack 代碼、待辦事項需註釋；避免流水賬式逐行註釋。
• 比例：註釋行數 ≥ 代碼行數 20%。

四、 文件結構順序

1. package 聲明
2. import：標準庫 → 第三方 → 本地，字母序；同包用 *。
3. 文件頭註釋
4. 類/接口註釋 + 定義（extends/implements 各佔一行）
5. 靜態常量 → 實例常量 → 靜態變量 → 實例變量（public 需 Javadoc）
6. 構造器（參數多者優先）
7. clone()、toString()（每個類必須實現）
8. 業務方法（邏輯相關者分組，組間空行）
9. main 方法（如有）置底

工具落地建議

• Eclipse/IntelliJ 導入統一 formatter.xml、checkstyle.xml，CI 流水線集成靜態檢查。
• 新建文件模板預置文件頭、版權聲明。
• Code Review 將規範作為硬性門檻。

總結

規範非束縛，乃自由之基。團隊應根據項目特點裁剪上述標準，工具化固化，文化化推廣，讓「寫出整潔代碼」成為肌肉記憶。