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

發行項
12/20/2024

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

命名規則

有效的標識碼必須遵循這些規則。 C# 編譯程式會針對未遵循下列規則的任何識別碼產生錯誤：

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

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

如需有效標識碼的完整定義，請參閱 C# 語言規格中的標識元一文。

重要

C# 語言規格只允許字母（Lu、Ll、Lt、Lm 或 Nl）、數位（Nd）、連接（Pc）、結合（Mn 或 Mc）和格式（Cf）類別。利用 _自動替換超出範圍的所有項目。這可能會影響某些 Unicode 字元。

命名慣例

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

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

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

提示

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

在下列範例中，在處理 protected 和 protected internal 元素時，也會適用標示為 public 之元素的指導方針，這些元素全都可供外部呼叫者看見。

Pascal 案例

在命名 class、interface、struct或 delegate 類型時，請使用 Pascal 大小寫（“PascalCasing”）。

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 類型的成員時，例如字段、屬性、事件，請使用pascal大小寫。此外，請針對所有方法和區域函式使用 Pascal 大小寫。

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 欄位時，請使用 camel casing（“camelCasing”），並以 _為前綴。命名局部變數時，請使用駝峰式命名法，包括委派類型的實例。

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 { /*...*/ }

Do 具有「T」的描述性類型參數名稱前置詞。

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

考慮指出參數名稱中類型參數上放置的條件約束。例如，一個限制為 ISession 的參數可能會被命名為 TSession。

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

額外的命名慣例

不包含指令的範例，應使用命名空間限定。如果您知道預設會在項目中匯入命名空間，則不需要完整限定該命名空間的名稱。如果限定名稱太長而無法放在單行內，可以在點之後斷開，如下列範例所示。
```
var currentPerformanceCounterCategory = new System.Diagnostics.
    PerformanceCounterCategory();
```
您不需要變更使用 Visual Studio 設計工具建立的物件名稱，使其符合其他指導方針。

共用方式為