Java 編碼規範完整指南：命名、註解、檔案結構與最佳實踐

一、 命名規範

原則：完整英文描述、駝峰式大小寫、避免縮寫、長度<15 字元、避免相似名稱、禁止底線（靜態常數除外）。

二、 註解規範

原則

• 增加清晰度、簡潔、先寫註解再寫代碼、註解「為什麼」而非「做什麼」。

風格與適用範圍

• Javadoc（/** ... */）：類別、介面、方法、欄位聲明前。
• C 風格（/* ... */）：暫時停用代碼，註明作者、日期、保留原因。
• 單行（// ）：方法內部業務邏輯、代碼區塊、暫時變數。// 後必接空格。

必須註解的部分

• 類別：用途、不變條件
• 介面：用途、使用/誤用方式
• 一般方法：功能、參數含義、回傳值
• 方法內部：控制結構、處理順序、為何如此實作
• 參數：含義、約束、前置條件
• 欄位：描述

三、 Java 檔案結構規範

1. 版權聲明：檔案開頭 /** Copyright © 2000 ... */
2. Package/Import：package 在前，標準包優先，按字母序；同包子目錄用 *。
3. 類別註解與定義：Javadoc 後接 public class X extends Y implements Z {（extends/implements 分行）。
4. 類別欄位：public 欄位必須 Javadoc；protected/private 名稱明確可省略。
5. 存取方法：簡單 getter/setter 可單行；集合類提供 add/remove 方法；其它方法勿單行。
6. 建構子：參數遞增順序（少參數在前）。
7. clone 方法：可複製類別實作。
8. 一般方法：完整 Javadoc（@param, @return, @throws）。
9. toString()：每個類別建議實作。
10. main()：測試代碼置於類別底部。

四、 其他編碼慣例

• 文件化：強制 Javadoc，不建議 @author（代碼非個人擁有）。
• 縮排：2 空格，禁止 Tab 字元（工具設定 Tab=2 空格並轉換）。
• 行寬：80 字元；過長語句在逗號/運算元後換行，續行再縮排 2 空格。
• 大括號：單獨佔行；if (i>0) { i++; }（正確），if (i>0) { i++; };（錯誤）。
• 括號：緊貼字元無空格；CallProc(param)（正確），CallProc( param )（錯誤）。無意義括號禁止。
• JSP 命名：動詞開頭 camelCase，如 viewMessage.jsp。
• Servlet 命名：服務對象 + Service，如 UserService。

五、 程式設計建議

• 字串處理：大量拼接用 StringBuffer（或 StringBuilder），完成後 toString() 轉 String。
• 同步最小化：必要時才用 synchronized，區塊級鎖優於方法級。
• 避免 Vector：同步化導致效能損失，優先 ArrayList。
• 面向介面編程：回傳型別用介面（如 List 而非 ArrayList），實作變更不影響呼叫端。
• 資料庫結果集：用欄位名（getField("name")）而非索引存取，免受 SQL 變更影響。