C# 編碼規範與良好程式習慣完整指南

核心原則：可運行 ≠ 高效

「可運行代碼」容易，「高效、可維護、團隊友善」才是專業標準。

一、命名慣例

• 禁用匈牙利命名法：m_strName, nAge ❌ → name, age ✅
• 語意化命名：salary 而非 sal；迴圈索引 i 可接受
• 無底線：變數名不含 _
• 檔名 = 類別名：HelloWorld.cs

二、排版與縮排

• 縮排：**Tab** (非 Space)
• 大括號**獨佔一行** (Allman 風格)
• 運算子/括號前後**各一空格
• 邏輯區塊間**空一行**
• 方法間**空一行**

// Good
bool SayHello(string name)
{
    DateTime now = DateTime.Now;
    string msg = $"Hello {name}, time: {now:t}";
    MessageBox.Show(msg);

    if (msg.Length > 100)
    {
        return false;
    }
    return true;
}

// Bad
bool SayHello(string name){
    string msg="Hello "+name;
    if(msg.Length>100){return false;}
    return true;
}

三、良好編程習慣

1. 檔案 ≤ 400 行，超過拆類別
2. 方法 ≤ 25 行，超過拆方法
3. 方法名自述功能：SavePhoneNumber 優於 SaveData + 註解
4. 單一職責：一個方法只做一件事
5. 用 C# 關鍵字型別：int/string/object 而非 Int32/String/Object
6. 魔術數字 → const/enum
7. 字串常數 → 資源檔
8. 少用成員變數：偏好區域變數傳遞
9. 離散值用 enum：MailType.Html 而非 "Html"
10. 欄位私有，屬性公開
11. 避免硬編碼路徑：相對路徑、AppDomain.CurrentDomain.BaseDirectory
12. 啟動自檢：檔案、DB 連線、設定檔
13. 錯誤訊息具體且可行動：「資料庫連線失敗，請確認帳號密碼」而非「錯誤發生」
14. 使用者訊息簡短友善，日誌完整詳細

四、註解原則

• **不**逐行註解、不註解每個變數宣告
• **僅**在「為什麼」非顯而易見處註解
• 好命名 = 少註解
• 公用 API **必寫 XML 文件註解** (///)

五、例外處理

• 捕獲具體例外類型，避免 catch (Exception)
• using 區塊管理 IDisposable
• 異常重拋用 throw; 保留堆疊
• 自訂例外繼承 Exception，以 Exception 結尾命名

結語

規範非束縛，而是團隊溝通的共同語言。從今天開始，每次 Commit 前自我檢視：
「這段代碼，六個月後的我還能秒懂嗎？」