前言：為什麼需要命名規範？
程式碼是給人讀的，順便給電腦執行。統一的命名規範能降低認知負荷、減少溝通成本、提升程式碼可讀性與維護性。本文整理涵蓋類型、成員、變數、命名空間、註解等全方位的 C# 命名慣例，參考 Microsoft 官方指南與業界最佳實踐，適合團隊專案直接採用或客製化調整。
一、類型層級命名規範
1. 類別
| 分類 | 規則 | 範例 | 說明 |
|---|
| 一般類別 | 名詞/名詞片語，PascalCase | Customer, OrderProcessor | 體現職責 |
| 屬性類別 | 以 Attribute 結尾 | ObsoleteAttribute | 慣例後綴 |
| 例外類別 | 以 Exception 結尾 | InvalidOperationException | 語義明確 |
| 單例/全域類別 | 以 Class 結尾 | ApplicationClass, SystemClass | 暗示單一實例 |
| 基類 | 視情況以 Base 結尾 | ControllerBase, EntityBase | 非強制 |
| Windows Form | 以 Form 結尾 | LoginForm, MainForm | 專案類型識別 |
| Web Form / Page | 以 Page 結尾 | HomePage, ProductPage | ASP.NET 慣例 |
2. 介面
- 強制前綴
I（大寫 I）
- 以形容詞或名詞片語命名，強調能力
- 範例：
IDisposable, IComparable, ISortable, IRepository
3. 列舉與結構
| 類型 | 規則 | 範例 |
|---|
| 列舉 | 名詞/名詞片語，建議複數形式，PascalCase | ColorButtons, FileAccessModes |
| 列舉值 | PascalCase | ColorButtons.Red, FileAccessModes.ReadWrite |
| 結構 | 名詞/名詞片語，可加 Record 或 Info 後綴 | CustomerInfoRecord, Point3D |
4. 委派
- 一般委派：動作名詞，
Action 後綴可選 → DataSeeker, FileProcessor
- 事件處理委派：強制
EventHandler 後綴 → DataChangedEventHandler, ButtonClickEventHandler
5. 模組
- 名詞命名 +
Module 後綴
- 範例：
SharedFunctionsModule, UtilityModule
通用原則
- 所有組成單字首字母大寫
- 禁止全大寫（
XML 等公認縮寫除外）或全小寫
- 避免底線
_ 分隔單字
二、成員命名規範
1. 方法
- 動詞/動詞片語，PascalCase
- 不區分 Function/Sub，不標示回傳型別
- 範例：
Open, CalculateTotal, GetCustomerById, SaveChangesAsync
- 參數命名見「變數命名」，預設使用
byVal（C# 預設傳值）
- 多載方法同名，參數列表區分
2. 屬性
- 名詞/名詞片語，PascalCase
- 布林屬性可加
Is, Can, Has 前綴 → IsEnabled, HasChildren
- 集合屬性用複數 →
Customers, OrderItems
- 範例：
Concentration, Customer, MaxRetryCount
3. 事件
- 動詞/動詞片語，PascalCase
- 以時態表示觸發時機：
Click（發生時）、Clicked（已發生）、Clicking（發生中）
- 配合
EventHandler 委派 → event EventHandler Click;
- 事件引數類別以
EventArgs 結尾 → DataChangedEventArgs
4. 欄位
- 私有實例欄位：
_camelCase（底線 + 駝峰） → _customerName, _maxRetryCount
- 私有靜態欄位：
_camelCase 或 s_camelCase → _instanceCount
- 公開/受保護欄位：禁止，改用屬性
- 常數：
PascalCase → DefaultTimeout, MaxBufferSize
三、區域變數與參數命名
| 類型 | 規則 | 範例 | 反例 |
|---|
| 一般區域變數 | 有意義名詞，camelCase | index, nextMonthExpenditure, customerName | a, x1, temp |
| 參數 | camelCase | commandString, copyNumber | str, num |
| 迴圈計數器 | 單字母可接受 | i, j, k | |
| Lambda 參數 | 單字母或簡短語意 | x => x.Name, (sender, e) => {} | |
| UI 控制項 | 語意名稱 + 型別後綴 | cancelButton, colorChooserPanel, fileOpenDialog | btnCancel, pnlColor |
命名長度原則
- 作用域越大，名稱越具描述性
- 避免過長（
VariableUsedToStoreSystemInformation → SystemInformation）
- 避免過短失去語意（
sysInfo → systemInfo）
四、特殊元素命名
標籤
- 全大寫，底線分隔，
_ 開頭
- 範例：
_ERROR_HANDLER_LABEL, _RETRY_LOGIC_START
- 目的：與一般程式碼元素完全區隔（
goto 慎用）
命名空間
- 格式：
公司名.產品名[.功能領域複數]
- 範例：
MyCompany.ProductName, MyCompany.ProductName.CustomControls
- 專案屬性設定 Root Namespace，避免程式碼中重複
namespace 宣告
五、註解規範
- XML 文件註解（
///）：所有公開 API 必須提供，支援 IntelliSense 與文件產生
- 單行註解（
//）：解釋「為什麼」而非「做什麼」
- 區塊註解（
/* */）：暫時停用程式碼或大段說明
- TODO/HACK/NOTE：標準標記 →
// TODO: 重構此演算法, // HACK: 臨時修正相容性問題
六、現代 C# 風格補充
檔案與類別對應
- 一檔一類，檔名與類別名相同
- 部分類別（
partial）以 ClassName.Purpose.cs 命名 → Customer.Validation.cs
using 指示詞排序
System 命名空間優先- 第三方套件
- 專案內部命名空間
- 每群組字母排序，群組間空一行
新語法特性應用
- 建構函式初始化：
new Customer { Name = "Tom", Age = 30 }
- 解構式賦值：
var (name, age) = GetPerson();
- 模式比對：
if (shape is Circle c) { ... }
- 不可變記錄類型：
record Person(string Name, int Age);
七、團隊落地建議
- 建立
.editorconfig 強制編譯器/IDE 檢查風格
- 整合
StyleCop.Analyzers 或 Roslynator 至 CI 流程
- Code Review 時以規範文件為準，避免主觀爭論
- 定期檢視更新規範，納入新語法特性最佳實踐
- 新人入職必讀，附帶好/壞範例對照表
總結
好的命名是最廉價的文件。遵循一致的 PascalCase/camelCase/_camelCase 慣例，搭配語意清晰的英文單字，能讓程式碼自述其意。本指南提供完整規範框架，團隊可根據專案屬性（如領域術語、縮寫慣例）微調細節，核心精神始終是：讓下一個閱讀者（包含未來的自己）最快理解程式碼意圖。
