Java 代碼開發規範全指南：從排版到命名的企業級標準

前言

統一的代碼規範是團隊協作的基石，能有效降低維護成本、提升代碼可讀性。本文整理自企業級 Java 開發標準（WISHSOFT），涵蓋開發工具、排版、命名、註解、資料類型前綴、日誌規範六大維度。

一、開發工具規範

• 開發工具由專案負責人統一確定，全組統一使用
• 禁止私自整合非統一插件，如有需求需經負責人批准後統一部署
• 編碼格式（如 UTF-8）一經確定不得隨意修改

二、排版規範

核心原則：清晰、一致、可讀

1. 運算符間距：關鍵字/變數與運算符之間保留一空格，如 int iCont = 1;
2. 代碼塊分隔：邏輯獨立的代碼塊之間以空行分隔，如方法之間
3. 長語句換行：過長語句在低優先級運算符處換行，運算符置於新行行首
4. 縮進統一：使用 Tab 鍵縮進（一級一個 Tab），邏輯層次分明
5. 一行一句：嚴禁多條短語句寫在同一行
6. 大括號風格：{ 和 } 各佔一行，且與引用它們的語句左對齊
7. main 方法位置：若類中定義了 main(String[])，應置於類底部

三、命名規範

四、註解規範

核心原則：與代碼同步維護、就近原則、適度詳盡

• 邊寫代碼邊寫註解，修改代碼同步更新註解
• 變數/常量註解置於上方或右側，不可置於下方
• 全域變數需詳細說明用途、取值範圍、存取位置及注意事項
• 類、方法、成員變數必須生成 JavaDoc 註解（含實體類的 getter/setter）
• 方法內部邏輯由開發者視複雜度自行添加

類級 JavaDoc 模板

/**
 * 功能描述（做什麼用的）
 * @author lifw 20080320
 * @modify lifw 20080321
 * @modify lifw 20080322 (多個修改順序列出)
 * @copyright wishsoft
 */

常用 Javadoc 標籤

• @author：作者
• @version：版本
• @see：參考關聯
• @param：方法參數說明
• @return：返回值說明
• @exception：拋出異常說明

五、基本資料類型前綴表

其他物件類型隨項目擴充補充。

六、日誌組件規範

• log.debug()：置於代碼關鍵處，用於除錯，永久保留不刪除
• log.error()：置於 catch 區塊，記錄異常堆疊資訊

總結

良好的代碼規範不是束縛，而是自由的前提。建議團隊根據專案實際情況在此基礎上裁剪擴充，並配合 Checkstyle、SonarQube 等工具落地執行，讓規範真正發揮價值。