C# 編程規範與最佳實踐指南

前言：從「能跑」到「高效」的轉變

誰都會寫代碼，幾個月經驗就能寫出「可運行的應用程序」。但要以最高效率、最佳結構編寫代碼，則需要長期的學習與實踐。大多數程序員只關注「能跑」，而忽略了「高效」。想成為團隊中最受重視的專業人士？掌握高效編碼藝術，從這份規範開始。

一、 命名慣例與規範

統一的命名風格能大幅提升代碼可讀性，降低維護成本。

1. 大小寫規則

• PascalCase（帕斯卡命名法）：所有單詞首字母大寫，其餘小寫。適用於類名、方法名、屬性名、命名空間。
• camelCase（駝峰命名法）：首單詞小寫，後續單詞首字母大寫。適用於變量、方法參數、局部變量。

2. 具體命名示範

// 類名 - PascalCase
public class HelloWorld { ... }

// 方法名 - PascalCase
public void SayHello(string name) { ... }

// 變量與參數 - camelCase
int totalCount = 0;
void SayHello(string name) {
    string fullMessage = "Hello " + name;
}

3. 禁用匈牙利命名法

早期習慣用類型前綴（如 m_sName、nAge），但在 .NET 規範中不推薦。所有變量統一使用 camelCase，不加類型或 m_ 前綴。

4. 命名原則

• 語義化、描述性：用 name、address、salary 代替 nam、addr、sal。
• 避免單字母變量（i、n、x），改用 index、temp。唯一例外：僅作循環計數且不在循環體外使用的迭代變量，可保留 i。
• 不使用下劃線（_）作為分隔符。
• 命名空間遵循標準模式：CompanyName.ProductName.TopLevelModule.BottomLevelModule。

5. 文件名與類名一致

類 HelloWorld 對應文件 HelloWorld.cs（或 .vb），便於快速定位。

二、 縮進與間距

• 縮進使用 Tab，不使用空格。
• 註釋與代碼對齊。
• 花括號 {} 與外層代碼對齊，另起一行（Allman 風格）。
• 邏輯分組之間空一行，增強可讀性。
• 類內方法之間僅空一行。
• 運算符與括號前後各留一空格：if ( showResult == true ) 而非 if(showResult==true)。

三、 良好編程習慣

1. 控制文件與方法大小

• 單文件超過 300~400 行應拆分類。
• 單方法控制在 1~25 行；超過 25 行拆分為多個方法。

2. 方法名自述職責

// 好：名稱即文檔
void SavePhoneNumber(string phoneNumber) { ... }

// 差：需靠註釋解釋
void SaveData(string phoneNumber) { ... }

3. 單一職責原則

一個方法只做一件事。將「保存地址」與「發送通知郵件」拆分為兩個獨立方法，而非合併在一個 SaveAddress(address, email) 中。

4. 優先使用 C# 內建類型別名

// 推薦
int age; string name; object contactInfo;

// 不推薦
Int16 age; String name; Object contactInfo;

5. 消除魔術數字與硬編碼字符串

• 用 const 或 readonly 替代固定數值。
• 字符串常量移至資源文件（.resx），便於本地化與維護。

6. 減少成員變量，偏好局部變量與參數傳遞

共享成員變量會導致狀態難以追蹤；改用局部變量並通過參數傳遞，降低耦合。

7. 善用 enum 表達離散值

enum MailType { Html, PlainText, Attachment }
void SendMail(string message, MailType mailType) { ... }

優於字符串判斷 case "Html"，編譯期即可檢查類型安全。

8. 封裝字段，暴露屬性

成員變量聲明為 private，對外提供 public/protected 屬性（Property），保護內部狀態。

9. 路徑處理與環境假設

• 不使用絕對路徑（如 C:\），改用相對路徑或可編程路徑（AppDomain.CurrentDomain.BaseDirectory、Environment.GetFolderPath）。
• 啟動時執行「自檢」：驗證必要文件、數據庫連接、配置文件是否存在；缺失時自動創建默認配置或給出友好錯誤提示。

10. 錯誤訊息設計原則

• 具體可行：「更新數據庫失敗，請確認登錄 ID 與密碼是否正確」 優於 「應用程序出錯」。
• 用戶端簡短友好，日誌端詳盡完整：便於問題診斷。

四、 註釋哲學

• 不為每行代碼寫註釋；好代碼勝過壞註釋。
• 僅在「必要處」註釋：複雜演算法、非直觀邏輯、特殊數值初始化原因。
• 註釋要正確、無拼寫錯誤、標點規範；過期註釋比無註釋更害人。
• 目標：代碼自述性強，無需註釋即可理解。

五、 異常處理鐵律

1. 絕不「吞掉」異常：catch { } 或 catch { return null; } 會掩蓋錯誤，導致問題永遠無法被發現。
2. 用戶見友好提示，日誌記完整上下文（時間、方法、類名、堆疊）。
3. 捕獲具體異常類型（FileIOException），而非基類 Exception。
4. 不在每層方法都 try-catch；讓異常冒泡至應用層統一處理器（Application.ThreadException、AppDomain.UnhandledException），在開發期暴露更多 Bug。
5. 縮小 try 區塊範圍：每個具體操作獨立 try-catch，便於定位錯誤源並給出針對性提示。
6. 自定義異常繼承 ApplicationException，而非 SystemException。

遵循這套規範，不僅能寫出「能跑」的代碼，更能產出可維護、可擴展、團隊協作友好的高質量軟件。從今天開始，把每一行代碼都當作給未來的自己（和同事）看的文檔來編寫吧！