C# 程式碼撰寫規範：命名慣例、格式化、註釋與最佳實務完整指南

前言

一致的程式碼風格能大幅提升可讀性、可維護性與團隊協作效率。本文整理 C# 官方慣例與業界最佳實務，涵蓋命名規則、排版格式、註釋規範三大面向，並提供可直接套用的 EditorConfig 範例。

一、命名規範

核心原則

• 名稱應揭示「是什麼」而非「如何做」：GetNextStudent() 優於 GetNextArrayElement()。
• 避免縮寫 (除非領域通用如 Id, Xml, Http)。
• 長度適中：足以表達意圖，不過度冗長。

大小寫風格對照表

具體命名建議

• 布林屬性/變數：加 Is、Has、Can、Should 前綴 → IsValid, HasChildren。
• 集合屬性：使用複數名詞 → Customers, OrderItems。
• 事件處理器：On + 事件名 → OnClick, OnOrderCompleted。
• 委派類型：以 Handler 結尾 → EventHandler, ProgressHandler。
• 異常類別：以 Exception 結尾 → ValidationException。
• 避免：單字母 (除迴圈索引)、底線開頭 (私有欄位用 _)、匈牙利標記法。

二、程式碼格式化

縮排與對齊

• 縮排：4 個空格 (不使用 Tab)。
• 大括號：Allman 風格 (另起一行)，或 K&R (行尾) —— 專案統一即可。

// Allman (推薦)
if (condition)
{
    DoSomething();
}

// K&R
if (condition) {
    DoSomething();
}

行長度與換行

• 單行上限：120 字元 (現代螢幕建議)。
• 換行縮排：2 層縮排 (8 空格)。

string sql = "SELECT Id, Name, Email, CreatedAt "
    + "FROM Customers "
    + "WHERE IsActive = 1 "
    + "ORDER BY CreatedAt DESC";

空白行與空格

• 邏輯區塊間保留 1 空行。
• 運算子前後、逗號後、分號後 (for 迴圈) 加空格。
• if (x)、method(arg) 關鍵字/方法名與括號間無空格。

SQL 陳述式格式

SELECT FirstName, LastName
FROM Customers
WHERE Region = 'WA'
  AND IsActive = 1
ORDER BY LastName;

三、註釋規範

XML 文件註釋 (公開 API 必須)

/// 

/// 依使用者編號取得完整姓名。
/// 
/// 使用者唯一識別碼，不可為 null。
/// 格式為「姓 名」的完整姓名；找不到時回傳空字串。
///  為 null。
public string GetFullName(string userId)
{
    if (userId == null) throw new ArgumentNullException(nameof(userId));
    // ...
}

行內註釋

• 置於程式碼上方，而非行尾 (行尾註釋難維護)。
• 解釋「為什麼」而非「做什麼」 (程式碼已說明做什麼)。
• 使用 // TODO:, // HACK:, // NOTE:, // BUG: 標籤標記待辦/技術債。

區塊註釋

• 使用 /* ... */ 或連續 //。
• 不使用裝飾性框線 (如 **********)。
• 部署前移除暫時/除錯註釋。

複雜邏輯重構優於註釋

若需要大量註釋才能理解的程式碼，優先考慮提煉方法、引入說明性變數、使用設計模式 重構，而非堆砌註釋。

四、EditorConfig 範例 (專案強制風格)

在專案根目錄建立 .editorconfig，IDE (VS/VS Code/Rider) 將自動強制套用：

root = true

[*.cs]
indent_style = space
indent_size = 4
end_of_line = crlf
charset = utf-8-bom
trim_trailing_whitespace = true
insert_final_newline = true

# 命名規則
dotnet_naming_rule.interface_naming.severity = suggestion
dotnet_naming_rule.interface_naming.symbols = interface_symbols
dotnet_naming_rule.interface_naming.style = pascal_case_with_i_prefix

dotnet_naming_symbols.interface_symbols.applicable_kinds = interface
dotnet_naming_symbols.interface_symbols.applicable_accessibilities = public,internal

dotnet_naming_style.pascal_case_with_i_prefix.capitalization = pascal_case
dotnet_naming_style.pascal_case_with_i_prefix.required_prefix = I

# 公開成員需 XML 註釋
dotnet_diagnostic.CS1591.severity = warning

# 框架建議
csharp_style_var_for_built_in_types = true:suggestion
csharp_style_var_when_type_is_apparent = true:suggestion
csharp_prefer_simple_default_expression = true:suggestion
dotnet_style_prefer_is_null_check_over_reference_equality_method = true:suggestion

五、快速檢核清單 (Code Review 用)