.NET 官方編碼標準與命名規範完整指南

前言

編碼標準不影響功能，但決定代碼的可讀性、可維護性與團隊協作效率。本文整理自微軟官方指導方針，涵蓋命名、註釋、格式三大面向，供專案制定內部規範參考。

一、命名規範

核心原則

• 名稱表達「是什麼」而非「怎麼做」，保持抽象層級。
• 長度適中：足夠表達意圖，避免冗長。
• 區分唯一性（編譯器需求）與表達性（人類閱讀）。

大小寫風格

具體建議

• 方法：動詞/動詞片語，如 GetUserList、SaveChanges。避免 AnalyzeThis、DoIt。
• 布林屬性/變數：前綴 Is/Can/Has，如 IsValid、HasPermission。
• 集合屬性：複數名詞，如 Users、OrderItems。
• 介面：以 I 開頭 PascalCase，如 IDisposable、IUserRepository。
• 泛型型別參數：單一大寫字母或 T 開頭，如 T、TKey、TValue。
• 避免：匈牙利標記法（strName、iCount）、縮寫（除非領域通用如 Id、Xml）、同音異義詞（write/right）。

資料庫命名

• 資料表：單數名詞，如 Employee（非 Employees）。
• 欄位：不含資料表前綴，如 LastName（非 EmployeeLastName）。
• 不在欄位名含資料型別。
• 預存程序：無 sp_ 前綴（系統保留），無 fn_、xp_。

二、註釋規範

原則

• 代碼應自述，註釋解釋「為什麼」而非「做什麼」。
• 註釋與代碼同步維護，過時註釋比無註釋更有害。
• 公開 API 必須提供 XML 文件註釋（///），支援 IntelliSense 與文件生成。

風格建議

• 使用完整句子，首字大寫，結尾加句號。
• 避免行尾註釋（除非變數宣告對齊）。
• 區塊註釋以空白行分隔代碼，不使用裝飾框線（**********）。
• 複雜演算法/邏輯分支務必註釋意圖與邊界條件。
• 修正錯誤/變通方案必須註釋原因與相關 Issue 號。
• 部署前移除 TODO、FIXME、調試用註釋。

XML 文件註釋範本

/// 

/// 計算訂單總金額（含稅與折扣）。
/// 
/// 訂單識別碼。
/// 應收總額。
/// orderId 為空或無效。
/// 
/// 呼叫前需確認訂單狀態為 Confirmed。
/// 
public decimal CalculateOrderTotal(string orderId) { ... }

三、格式規範

縮排與大括號

• 統一 4 空格縮排（非 Tab）。
• 大括號風格任選其一並全專案一致：
  • Allman（新行）：if (...) { → } 各佔一行。
  • K&R（同行）：if (...) { ... } 右括號獨立行。

行長度與換行

• 建議單行 ≤ 130 字元，避免水平捲動。
• 長運算式換行時，運算子置於行尾（非行首），明確表示續行。

空白行與分組

• 邏輯相關代碼群組之間保留一空行。
• 欄位、建構子、屬性、方法、事件等區塊以空白行分隔。

SQL 陳述式格式

SELECT FirstName, LastName
FROM Customers
WHERE Region = 'WA'
  AND Status = 'Active'
ORDER BY LastName;

HTML/XHTML

• 標籤小寫，屬性值加雙引號，必須閉合標籤。
• 遵循 XHTML 或 HTML5 標準，確保驗證通過。

總結

編碼標準是團隊共識的產物。建議：

1. 以此文為基礎，召開會議制定《專案編碼規範 v1.0》。
2. 接入靜態分析工具（StyleCop、SonarQube、EditorConfig）強制執行。
3. Code Review 時將「符合規範」作為檢查項目之一。
4. 定期回顧調整，避免教條主義。

好的代碼像好散文：結構清晰、用詞精確、閱讀愉悅。規範是達到此目標的基石。