PHP 編碼規範完整指南：PSR 風格、命名慣例、註釋標準、SQL/HTML/Smarty 規範

為什麼需要編碼規範？

• 軟體生命週期 80% 成本在維護，規範降低理解成本。
• 團隊協作需統一風格，減少 Code Review 爭論。
• 規範即文件，新成員快速上手。

核心排版規範

命名慣例

禁用拼音命名（如 $yong_hu），國際化團隊無法理解。

註釋標準（PHPDoc）

<?php
/**
 * 檔案級說明
 *
 * @package    MyProject\Module
 * @version    1.0.0
 * @author     Name <email@example.com>
 * @copyright  2024 Company
 * @license    MIT
 */

/**
 * 取得使用者列表
 *
 * @param int    $limit  筆數限制
 * @param int    $offset 起始位移
 * @param string $role   角色篩選
 * @return array 使用者陣列
 * @throws \InvalidArgumentException 參數錯誤
 */
function get_user_list(int $limit = 20, int $offset = 0, string $role = ''): array
{
    // ...
}
?>

• 檔案頭、類別、介面、公有方法必須有 PHPDoc。
• 私有/保護方法視複雜度加註。
• 廢棄代碼直接刪除，勿保留註釋代碼。
• 註釋以繁體中文為主，關鍵術語可保留英文。

流程控制規範

• switch 每個 case 必須有 break 或 return，若故意貫穿需註釋 // no break。
• if/else if/else 統一用 elseif（無空格），條件判變數優先（if ($id && check($id))）。
• 三元運算子僅用於簡單賦值，禁止巢狀、禁止函式呼叫。

變數與安全

• 使用前必須初始化，配合 isset()/empty()/?? 防 Notice。
• 字串優先單引號，無變數插值時免解析開銷。
• 關聯陣列鍵名必須加引號：$arr['key']，否則視為常數查找，效能損失 3 倍並觸發 Notice。
• 自增/自減獨立一行，勿用於運算式中（$arr[++$i] ❌）。
• require_once/include_once 替代 require/include，防重複載入。

SQL 規範

• 關鍵字大寫，欄位/表名反引號包裹。
• 明確列出欄位，禁用 SELECT *。
• 條件值參數化，prepare() + bind_param()。
• 分頁必加 LIMIT，統計用 COUNT(*)。
• INSERT 必須指定欄位名：INSERT INTO tbl (a,b) VALUES (?,?)。

Smarty 模板規範

• 界定符 <{ }>。
• 屬性值單引號：<{if $var eq ''}>。
• 條件修飾符用 eq/neq/gt/lt，避免 ==/!=/>/< 被 DW 轉義。
• HTML 屬性條件輸出整體包雙引號：<div class="<{if $cond}>active<{else}>normal<{/if}>">。