Coding Style

TLDR

• 命名規則：除 Variables 使用 Camel Case 外，其餘成員多採 Pascal Case；Fields 不加前綴詞；Interface 以「I」開頭；縮寫規則依據單字數量與大小寫慣例處理。
• 排序規則：遵循 StyleCop (SA12xx) 規範，優先順序為 Access Modifiers、Static、Readonly 等；Using 宣告需依 System. 開頭、字母順序及 Alias 分類排列。
• 註解風格：傾向 Clean Code 風格，註解應說明「為什麼」而非「做什麼」；使用 // 單行註解；公開 API 需使用 XML 文件註解；利用 TODO、HACK 等關鍵字標記待辦事項。
• 排版規範：左大括弧採同行風格；運算子換行時，二元運算子應置於新行開頭；三元運算子過長時建議換行以維持可讀性；檔案末端應保留一個空行。

Naming Rules

在 C# 命名規範中，應根據成員類型選擇大小寫格式，並避免使用過時的前綴詞。

• 大小寫慣例：除了 Variables 使用 Camel Case 外，其餘成員（如 Methods, Classes）多採用 Pascal Case。
• Fields 命名：
  • Public 與 Internal Fields 使用 Pascal Case。
  • Constants 與 Static Readonly Fields 使用 Pascal Case。
  • 其餘 Fields 使用 Camel Case，且不須加上「」、「m」或「s_」等前綴詞。
• Interface 與泛型：Interface 名稱開頭必須加上「I」；泛型參數若為單一且任意型別，使用「T」即可。
• 縮寫處理：
  • 三個單字以上的縮寫（如 Sql），僅首字母大寫。
  • 兩個單字的縮寫（如 Id），僅首字母大寫。
  • 兩個單字的縮略字（如 IO），則全大寫或全小寫。

Ordering Rules

程式碼排序應遵循 StyleCop (SA12xx) 規範，以確保結構一致性。

• 成員排序：依據 Access Modifiers（public > internal > protected > private）進行排序。
• 關鍵字順序：Constant Field 必須在 Non-constant Field 前；Static 必須放在 Non-static 上方；Readonly Field 必須放在 Non-readonly Fields 前面。
• Using 排序：
  • 優先順序：Using Namespaces > Using Static > Using Alias。
  • Namespaces 內部：System. 開頭放最前面，其餘依字母排序。
• Method 排序建議：不完全拘泥於 Access Modifiers，建議將同質性高或有呼叫關係的 Method 排在一起，以利閱讀。

完整範例

以下為建議的程式碼結構範例：

using Namespace;
using static Namespace.StaticClassName;
using Namespace = Alias;

public class ClassName {
    #region Fields
    public const int ConstantName = 0;
    public readonly static int ReadonlyStaticFieldName = 0;
    private static int StaticFieldName = 0;
    private int fieldName = 0;
    #endregion

    public int PropertyName { get; set; }

    public void MethodName() {
        MethodA();
    }

    private void MethodA() { }
}

註解

註解應具備目的性，避免冗餘說明。

• 單行註解：使用 // 開頭並在後方空一格。傾向說明「為什麼要做這件事」，而非紀錄「程式碼正在做什麼」。
• 文件註解：公開的 Class、Struct、Interface 或 Member 應使用 XML 文件註解。若需標記泛型，請使用 {} 取代 <> 以免 XML 解析錯誤。
• 工作清單：利用 Visual Studio 內建關鍵字管理任務：
  • TODO：標示未來需要完成的功能。
  • UNDONE：標示正在進行但尚未完成的工作。
  • HACK：標示暫時性的解決方案，需儘速修正。

排版

排版規範旨在提升程式碼的可讀性與一致性。

• 左大括弧：採同行風格（例如 if () {）。
• 空格使用：逗號後方、控制流程關鍵字後方、運算子前後（++ 與 -- 除外）皆應加入空格。
• 運算子換行：採用「out-of-line style」，二元運算子（如 +、||）在換行時應置於新行開頭，以利視覺區隔。
• 三元運算子：巢狀三元運算子務必換行，建議將子條件對齊以提高閱讀性。
• 檔案結尾：檔案末端應保留一個空行，以符合 Unix/Linux 換行慣例，避免編輯器顯示異常。

TIP

程式碼長度建議參考 80 至 120 字符的分隔線，適時換行可避免在小型螢幕上頻繁捲動，提升開發體驗。

---

異動歷程

• 2022-11-06 初版文件建立。