J2EE 專案程式碼撰寫規範完整指南

前言

在企業級 Java 開發中，統一的程式碼撰寫規範不僅能提升團隊協作效率，更能確保專案的可維護性與擴展性。本文整理了一套適用於 J2EE（現 Jakarta EE）專案的完整編碼標準，涵蓋套件命名、類別命名、變數與方法規範、註解標準、JSP 頁面組織以及專案目錄結構與交付規範，供開發團隊參考與落地。

一、套件命名規範

套件命名應清晰反映專案模組劃分，採用反向域名作為前綴，格式為：公司名稱.開發組名.專案名稱.功能模組。以下為常見模組的標準套件路徑：

• Servlet 類別：com.company.team.project.web.servlet
• 自訂標籤：com.company.team.project.web.tags
• 過濾器：com.company.team.project.web.filter
• Struts Action：com.company.team.project.web.struts.action
• ActionForm：com.company.team.project.web.struts.form
• Service 介面：com.company.team.project.web.service
• Service 實作類：com.company.team.project.web.service.impl
• DAO 介面：com.company.team.project.dao
• DAO 實作類：com.company.team.project.dao.impl
• POJO 與 Hibernate 映射檔：com.company.team.project.dao.hbm
• 全域公用類別/介面：com.company.team.project.global
• 工具類別：com.company.team.project.util

二、類別與介面命名規範

1. 基本原則

• 類別名稱採用 UpperCamelCase（大駝峰），每個單字首字母大寫，例如 StudentInfo。
• 介面名稱以大寫 I 開頭，後接大駝峰，例如 IStudentInfo。
• 實作類別以介面名稱移除 I 後綴 Impl 結尾，例如 StudentInfoImpl。

2. J2EE + SSH 框架專屬命名

三、變數、常數與方法命名規範

1. 成員變數

• 採用 lowerCamelCase（小駝峰），首字母小寫，單字間不使用底線。
• 建議宣告為 private，並提供公共的 getter/setter 方法。
• 範例：private int studentAge;

2. 常數

• 全部大寫，單字間以底線 _ 分隔。
• 必須宣告為 public static final。
• 範例：public static final String USER_NAME = "userName";

3. 方法

• 採用 lowerCamelCase，首字母小寫，動詞開頭，不使用名詞或底線。
• 範例：public boolean checkLogin(String name, String pwd) {}

四、註解文件規範（重點）

完整的註解是程式碼可讀性的關鍵，必須嚴格執行。

1. 類別註解模板

/**
 * 類功能描述：（簡述類的核心職責）
 * @author：作者名稱
 * @version：版本號（從 1.0 起，記錄修改時間、作者、修改內容）
 * @see 包名.參考類別名 （列出父類、引用類，每行一個，可省略）
 * 相關數據：（常量值或重要數據格式說明，可省略）
 */
public class AdminDAO { ... }

2. 變數/常數註解

/**
 * 變數功能描述：（簡述變數用途）
 */
public int age;

3. 方法註解模板

/**
 * 方法功能解釋
 * @param 參數名 參數說明（類型可寫在後，每行一個參數）
 * @return 回傳值說明（多種情況同行）
 * @see 類別#參考方法 （相關聯方法，擇要列出）
 * @exception 異常類別 （可能拋出的異常，每行一個）
 */
public boolean editAdminPassword(int adminId, String oldPassword, String password)
    throws UserException, ServiceException { ... }

五、JSP 頁面命名規範

• 檔名採用 lowerCamelCase，首字母小寫，後續單字首字母大寫。
• 名稱應體現頁面功能，建議與模組名稱關聯。
• 範例：login.jsp、register.jsp、messageBoard.jsp

六、專案目錄結構規範

依據 Eclipse/Maven 標準佈局組織資源，便於模組化管理：

src/                    -- Java 原始碼
WebRoot/                -- Web 應用根目錄
├── images/             -- 全站公用圖片
├── css/                -- 全站公用樣式表
├── js/                 -- 全站公用 JavaScript
├── commons/            -- 公用片段、標籤檔
├── [功能模組名稱]/     -- 各業務模組獨立資源
│   ├── images/
│   ├── css/
│   ├── js/
│   └── *.jsp, *.html
└── WEB-INF/
    ├── classes/        -- 編譯後 class 檔（自動生成）
    ├── lib/            -- 依賴 JAR 包
    └── *.tld           -- 標籤庫描述檔

七、專案交付規範

專案驗收時需整理為標準產出物結構，體現專業度：

專案主目錄：[日期]_[班級/批次]_[組別]  例：20240520_JAVA01_GroupA
├── src/                -- 所有 .java 原始碼
├── database/           -- SQL 腳本、資料庫備份檔
├── source/             -- WebRoot 目錄下所有檔案
├── depend/             -- 編譯所需第三方 JAR
├── javadoc/            -- 所有類別生成的 Javadoc API 文件
├── war/                -- 打包後的 .war 檔
├── project/            -- 原始 IDE 專案檔
├── 產品說明書.doc      -- 圖文操作手冊
├── build.xml           -- Ant 建構腳本
└── 專案簡報.ppt        -- 專案展示簡報（教學用途）

注意： 完整專案必須包含一定量的有效測試資料，以支援系統功能演示。

結語

規範的價值在於堅持執行。建議團隊將上述標準納入 Code Review 清單，並配合 IDE 格式化模板與靜態分析工具，從源頭保證程式碼品質，讓專案在長期演進中保持清晰、健壯。