IDesign C# 編程規範（二）：編碼慣例與實務準則

編輯：關於C語言

前言

本文為 IDesign C# 編程規範系列第二部分，涵蓋編碼慣例 33 項準則（第 1-33 條），著重於檔案組織、方法設計、錯誤處理、效能與可維護性。

檔案與專案組織

#	規範	說明
1	單一類別單一檔案	避免多個類別共用一個 .cs 檔
2	單一命名空間單一檔案	一個檔案只貢獻類型給一個命名空間
3	檔案長度 ≤ 500 行	機器產生代碼除外
22	最小化公開型別	僅必要型別標記 public，其餘 internal
23	避免 friend assembly	增加組件耦合，改用公開介面
24	避免依賴特定路徑載入組件	使用相對路徑或 GAC
25	最小化 EXE 程式碼	業務邏輯放入類別庫，EXE 僅啟動

方法設計原則

#	規範	說明
4	方法長度 ≤ 25 行	超過即重構拆分
5	參數數量 ≤ 5	超過改用結構體/類別封裝
6	行寬 ≤ 80 字元	提升可讀性與列印相容
30	避免布林條件中直接呼叫函式	先存區域變數再判斷，利於除錯與閱讀
42	方法/屬性比 ≥ 2:1	介面/類別應以行為為主，非資料容器

布林條件重構範例

// 避免
if (IsEverythingOK()) { ... }

// 採用
bool ok = IsEverythingOK();
if (ok) { ... }

常數與魔術數字

#	規範	說明
11	絕不硬編碼數值	永遠宣告常數
12	const 僅用於自然常數	如一週天數、圓周率
13	readonly 用於執行期常數	建構子初始化、不可變參考

const vs readonly 範例

public class MyClass {
    public readonly int Number;        // 執行期決定，建構子賦值
    public MyClass(int someValue) {
        Number = someValue;
    }
    public const int DaysInWeek = 7;   // 編譯期常數，永不變
}

斷言與測試

#	規範	說明
14	每 5 行一個斷言	Debug.Assert 驗證前置/後置條件
15	白盒測試覆蓋每行	逐行走測而非僅黑盒

斷言範例

using System.Diagnostics;
object GetObject() {
    object obj = GetObjectInternal();
    Debug.Assert(obj != null, "GetObjectInternal 不應回傳 null");
    return obj;
}

例外處理鐵律

#	規範	說明
16	僅捕獲可明確處理的例外	避免吞沒例外
17	重拋保留原始堆疊	使用 `throw;` 而非 `throw ex;`
18	避免錯誤碼回傳	改用例外
19	避免自訂例外類別	優先使用框架內建例外
20	自訂例外必繼承 ApplicationException	並提供自訂序列化

正確重拋模式

catch (Exception ex) {
    Log.Error(ex);
    throw;  // 保留原始堆疊追蹤
}

列舉設計

#	規範	範例
26	避免明確指派列舉值	`enum Color { Red, Green, Blue }`
27	避免指定列舉底層型別	預設 int 即可，除非互操作需求

控制流程規範

#	規範
28	if 永遠使用大括號
29	避免三元條件運算子 ?:
31	永遠使用零基底陣列
32	參考型別陣列顯式逐項初始化

陣列初始化範例

MyClass[] array = new MyClass[100];
for (int i = 0; i < array.Length; i++)
    array[i] = new MyClass();

封裝與屬性

機器產生代碼處理

#	規範
33	無 public/protected 欄位，改用屬性

#	規範
7	不手動修改機器產生代碼
7a	必須修改時，調整格式符合規範
7b	優先用 partial class 隔離手動維護部分

註解哲學

#	規範
8	避免註解顯而易見的事實
8a	程式碼應自說明：良好命名勝過註解
9	僅文件化前置條件、演算法洞見
10	避免方法層級文件
10a	API 文件用外部文件
10b	方法註解僅作工具提示