註釋

一、模板註釋區分

寫法	類型	特點
<!-- HTML註釋 -->	HTML原生註釋	會輸出到最終網頁原始碼，瀏覽器檢視原始碼可以看見
## 單行註釋	Velocity單行註釋	僅引擎辨識，不會輸出到頁面，作用到該行結尾
#* 多行註釋內容 *#	Velocity多行註釋	支援換行，不會輸出到頁面

開發建議：業務說明程式註釋優先使用## / #* *#，避免網頁原始碼外洩註釋內容。

二、變數命名規則

官方基礎命名規則

1. 變數第一個字元必須為英文字母（a‑z / A‑Z）
2. 後續可使用字元：字母、數字0‑9、底線_、減號-

減號 - 會產生運算子歧義

#set($name-d = "test")Code language: PHP (php)

執行會出現錯誤：Encountered "name" ... Was expecting one of:
原因：Velocity將 - 解讀為減法運算子！
引擎解析邏輯：$name - d，誤以為是變數$name減去變數d，造成語法衝突。

兩種解決方案：

1. 建議：改用底線命名（無歧義，通用規範）

#set($name_d = "hello world")Code language: PHP (php)

2. 使用大括號限定變數邊界（相容包含減號的變數名）

#set(${name-d} = "hello world")
${name-d}Code language: PHP (php)

合法／非法範例對照

# ✅合法
#set($name_d = "底線")
#set($name12d = "字母開頭加上數字")
#set(${name-1_2d} = "包含減號必須加大括號")

# ❌直接寫減號，沒有大括號 → 解析錯誤
#set($name-d = "發生錯誤！")
#set($name-1_2d = "發生錯誤！")Code language: PHP (php)

三、#set 語法書寫規範

標準寫法（括號前後空格可彈性調整，建議維持統一風格）

#set($變數名稱 = "值")Code language: PHP (php)

字串內容必須使用雙引號包覆；等號兩側建議保留空格，提升可讀性。

註釋