Java 基礎語法完整指南：源檔結構、命名規範、註解與文件化
Java 是純物件導向語言，所有程式碼必須包裹在類別中。本文詳細規範源檔撰寫規則、命名慣例、三種註解風格與 Javadoc 文件化工具用法，助你養成專業級編碼習慣。
一、源檔撰寫核心規則
1. 基本架構範例
// HelloDate.java
import java.util.Date; // 引入額外類別/套件
public class HelloDate {
/*
* 程式目的：輸出當前系統時間
*/
public static void main(String[] args) {
System.out.print("Hell, it's ");
System.out.println(new Date());
}
}
2. 關鍵規則解析
| 項目 | 規則 | 說明 |
|---|
| import | 引入額外類別 | java.lang 自動引入，無需 import |
| 類別宣告 | public class 類別名 | 類別名必須與檔名相同（含大小寫） |
| main 方法 | public static void main(String[] args) | 程式入口，args 存放命令列參數 |
| 多 main 方法 | 允許多個類別各有 main | 執行時由 JVM 呼叫指定類別的 main |
| 物件列印 | System.out.println(obj) | 自動呼叫 toString()，未覆寫則顯示位址 |
| 垃圾回收 | 自動管理 | 無引用物件自動回收，無記憶體洩漏風險 |
二、源檔命名強制規則
- 最多一個
public 類別。
- 若有
public 類別，檔名必須與該類別名完全相同（.java 副檔名）。
- 若無
public 類別，檔名任一類別名皆可。
三、非書面命名慣例（業界標準）
| 元素 | 慣例 | 範例 |
|---|
| 類別/介面 | PascalCase，縮寫全大寫 | DateTest, XMLExample |
| 方法/變數 | camelCase | getName, maxSize |
| 常數 | 全大寫 + 底線分隔 | MAX_SIZE, DEFAULT_TIMEOUT |
| 套件 | 全小寫，反向網域 | com.company.project |
四、良好編程習慣三要素
- 縮排：區塊縮排，一行一句，禁止多短句同行。
- 註解：有效程式碼 10-20%，註解貼近程式碼（上方/右側），修改碼必修改註解。
- 識別符命名：見名知意，完整單詞或公認縮寫，禁用單字元變數名。
五、關鍵字與識別符
- 關鍵字：Java 預留字（
class, public, static, void 等），不可作識別符。
- 識別符組成：字母、數字、
_、$；首字元不可為數字；嚴格區分大小寫。
六、三種註解風格
| 類型 | 語法 | 用途 | 範例 |
|---|
| 單行 | // 文字 | 簡短說明 | // 計算總和 |
| 多行 | /* 文字 */ | 區塊說明、暫時停用代碼 | /* 多行說明 */ |
| 文件註解 | /** 文字 */ | API 文件生成，支援標籤 | 見下方範例 |
文件註解標準寫法
/**
* 類別功能描述
* @author 作者名
* @version 1.0
* @since JDK 1.8
*/
七、內嵌式文件與 Javadoc 工具
- 原理：文件與程式碼同檔，透過特殊標記萃取。
- 工具：
javadoc.exe（JDK bin 目錄）。
- 輸出：HTML 格式 API 文件，含類別/方法/參數結構，瀏覽器可讀。
- 進階：可嵌入自訂 HTML 標籤美化輸出。
常用 Javadoc 標籤
@param 參數說明
@return 回傳值說明
@throws 例外說明
@see 參考連結
@deprecated 棄用標記
實務建議：將 Javadoc 整合至建構流程（Maven/Gradle javadoc:jar），持續發布最新 API 文件至內部 Nexus/Artifactory，提升團隊協作效率。
