C# 識別碼命名規則和慣例

發行項
02/26/2024

識別碼是您為類型 (類別、介面、結構、委派或列舉)、成員、變數或命名空間指派的名稱。

命名規則

有效的識別項必須遵守下列規則。 C# 編譯器會針對未遵循下列規則的任何識別項產生錯誤：

識別碼必須以字母或底線 (_) 開頭。
識別項可能包含 Unicode 字母字元、十進位數字字元、Unicode 連接字元、Unicode 組合字元或 Unicode 格式化字元。如需 Unicode 類別的詳細資訊，請參閱 Unicode 類別資料庫。

您可以使用識別碼上的 @ 前置詞，宣告與 C# 關鍵字符合的識別碼。 @ 不是識別項名稱的一部分。例如，@if 會宣告名為 if 的識別碼。這些逐字識別碼的主要目的是與使用其他語言宣告的識別碼達成互通性。

如需有效識別項的完整定義，請參閱 C# 語言規格中的識別項文章。

重要

C# 語言規格只允許字母 (Lu、Ll、Lt、Lm、Lo 或 Nl)、數字 (Nd)、連接 (Pc)、結合 (Mn 或 Mc) 和格式設定 (Cf) 類別。使用 _ 自動取代以外的任何項目。這可能會影響某些 Unicode 字元。

命名規範

除了規則之外，識別項名稱的慣例也會在整個 .NET API 中使用。這些慣例會提供名稱的一致性，但編譯器不會強制執行它們。您可以在專案中自由使用不同的慣例。

依照慣例，C# 程式針對類型名稱、命名空間和所有公用成員使用 PascalCase。此外，dotnet/docs 小組會使用下列從 .NET 執行階段小組編碼樣式採用的慣例：

以大寫 I 開頭的介面名稱。
以單字 Attribute 結尾的屬性類型。
列舉類型會針對非旗標使用單一名詞，並針對旗標使用複數名詞。
識別碼不應包含兩個連續底線 (_) 字元。這些名稱保留給編譯器產生的識別碼。
針對變數、方法和類別使用有意義的描述性名稱。
明確優先於簡潔。
針對類別名稱和方法名稱使用大駝峰式命名法。
針對方法參數和局部變數使用 camelCase。
將大駝峰式命名法用於常數名稱，包括欄位和本機常數。
私用實例欄位以底線（_）開頭，其餘文字為 camelCased。
靜態欄位以 s_ 開頭。此慣例不是預設的 Visual Studio 行為，也不是 Framework 設計指導方針的一部分，但可在 editorconfig 中設定。
請避免在名稱中使用縮寫或縮略字，但廣為人知且接受的縮寫除外。
使用遵循反向網域名稱標記法的有意義和描述性命名空間。
選擇代表組件主要用途的組件名稱。
請避免使用單一字母名稱，但簡單的迴圈計數器除外。此外，描述 C# 建構語法的語法範例通常會使用下列符合 C# 語言規格中所使用慣例的單一字母名稱。語法範例是規則的例外狀況。
- 將 S 用於結構，C 用於類別。
- 將 M 用於方法。
- 將 v 用於變數，p 用於參數。
- 將 r 用於 ref 參數。

提示

您可以使用程式碼樣式命名規則，強制執行涉及大寫、前置詞、尾碼和文字分隔符號的命名慣例。

在下列範例中，與標示 public 之元素相關的指導方針也適用於使用 protected 和 protected internal 元素時，而且會向外部呼叫者顯示所有指導方針。

大駝峰式命名法

命名 class、interface、struct 或 delegate 類型時，請使用首字母大寫 (「大駝峰式命名法」)。

public class DataService
{
}

public record PhysicalAddress(
    string Street,
    string City,
    string StateOrProvince,
    string ZipCode);

public struct ValueCoordinate
{
}

public delegate void DelegateType(string message);

命名 interface 時，除了在名稱前面加上 I 之外，還請使用 Pascal 大小寫。此前置詞清楚地向取用者指出其為 interface。

public interface IWorkerQueue
{
}

命名類型的 public 成員時 (例如欄位、屬性、事件)，請使用首字母大寫。此外，請針對所有方法和區域函式使用首字母大寫。

public class ExampleEvents
{
    // A public field, these should be used sparingly
    public bool IsValid;

    // An init-only property
    public IWorkerQueue WorkerQueue { get; init; }

    // An event
    public event Action EventProcessing;

    // Method
    public void StartEventProcessing()
    {
        // Local function
        static int CountQueueItems() => WorkerQueue.Count;
        // ...
    }
}

撰寫位置記錄時，請針對參數使用 Pascal 大小寫，因為它們是記錄的公用屬性。

public record PhysicalAddress(
    string Street,
    string City,
    string StateOrProvince,
    string ZipCode);

如需位置記錄的詳細資訊，請參閱屬性定義的位置語法。

駝峰式大小寫

命名 private 或 internal 欄位時，請使用首字母小寫 (「駝峰式大小寫」)，並在其前面加上 _。命名區域變數時，請使用首字母小寫，包括委派類型的執行個體。

public class DataService
{
    private IWorkerQueue _workerQueue;
}

提示

在支援陳述式完成的 IDE 中編輯遵循這些命名慣例的 C# 程式碼時，輸入 _ 將會顯示所有物件範圍成員。

使用為 private 或 internal 的 static 欄位時，請使用 s_ 前置詞，而且針對執行緒靜態，請使用 t_。

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

撰寫方法參數時，請使用駝峰式大小寫。

public T SomeMethod<T>(int someNumber, bool isValid)
{
}

如需 C# 命名慣例的詳細資訊，請參閱 .NET 執行階段小組的編碼樣式。

型別參數命名方針

下列指導方針適用於泛型型別參數上的型別參數。型別參數是泛型型別或泛型方法中引數的預留位置。您可以在 C# 程式設計指南中深入了解泛型型別參數。

務必使用描述性的名稱命名泛型型別參數，除非單一字母名稱足以表明，而且描述性名稱不會新增值。

public interface ISessionChannel<TSession> { /*...*/ }
public delegate TOutput Converter<TInput, TOutput>(TInput from);
public class List<T> { /*...*/ }

針對單一字母型別參數的類型，請考慮使用 T 做為型別參數名稱。

public int IComparer<T>() { return 0; }
public delegate bool Predicate<T>(T item);
public struct Nullable<T> where T : struct { /*...*/ }

描述性型別參數名稱前面務必加上 "T"。

public interface ISessionChannel<TSession>
{
    TSession Session { get; }
}

請考慮在參數名稱中指出放在型別參數上的條件約束。例如，受 ISession 條件約束的參數為可能稱為 TSession。

程式碼分析規則 CA1715 可用於確保適當地命名型別參數。

額外命名慣例

未包括 using 指示詞的範例會使用命名空間限定。如果您知道預設會在專案中匯入命名空間，則不需要完整限定該命名空間的名稱。如果限定的名稱太長無法顯示在同一行，則可以在點 (.) 之後中斷名稱，如下範例所示。
```
var currentPerformanceCounterCategory = new System.Diagnostics.
    PerformanceCounterCategory();
```
您不需要變更使用 Visual Studio 設計工具所建立物件的名稱，使其符合其他指導方針。