Reguły i konwencje nazewnictwa identyfikatorów języka C#

Artykuł
12/15/2023

Identyfikator to nazwa przypisywana do typu (klasa, interfejs, struktura, delegat lub wyliczenie), składowa, zmienna lub przestrzeń nazw.

Reguły nazewnictwa

Prawidłowe identyfikatory muszą być zgodne z tymi regułami. Kompilator języka C# generuje błąd dla wszystkich identyfikatorów, które nie są zgodne z następującymi regułami:

Identyfikatory muszą zaczynać się literą lub podkreślenia (_).
Identyfikatory mogą zawierać znaki litery Unicode, znaki cyfr dziesiętnych, znaki łączące Unicode, znaki łączące Unicode, znaki łączące znaki lub znaki formatowania Unicode. Aby uzyskać więcej informacji na temat kategorii Unicode, zobacz bazę danych kategorii Unicode.

Identyfikatory zgodne ze słowami kluczowymi języka C# można zadeklarować przy użyciu @ prefiksu identyfikatora. Element @ nie jest częścią nazwy identyfikatora. Na przykład @if deklaruje identyfikator o nazwie if. Te identyfikatory dosłowne są przeznaczone głównie do współdziałania z identyfikatorami zadeklarowanymi w innych językach.

Aby uzyskać pełną definicję prawidłowych identyfikatorów, zobacz artykuł Identyfikatory w specyfikacji języka C#.

Ważne

Specyfikacja języka C# zezwala tylko na literę (Lu, Ll, Lt, Lm, Lo lub Nl), cyfrę (Nd), łączenie (pc), łączenie (Mn lub Mc) i formatowanie (Cf). Wszystkie elementy zewnętrzne, które są automatycznie zastępowane przy użyciu polecenia _. Może to mieć wpływ na niektóre znaki Unicode.

Konwencje nazewnictwa

Oprócz reguł konwencje nazw identyfikatorów są używane w interfejsach API platformy .NET. Te konwencje zapewniają spójność nazw, ale kompilator ich nie wymusza. Możesz używać różnych konwencji w projektach.

Zgodnie z konwencją programy języka C# używają PascalCase nazw typów, przestrzeni nazw i wszystkich elementów członkowskich publicznych. Ponadto dotnet/docs zespół korzysta z następujących konwencji, przyjętych w stylu kodowania zespołu środowiska uruchomieniowego platformy .NET:

Nazwy interfejsów zaczynają się od litery I.
Typy atrybutów kończą się wyrazem Attribute.
Typy wyliczenia używają rzeczownika pojedynczego dla nonflags i rzeczownika w liczbie mnogiej dla flag.
Identyfikatory nie powinny zawierać dwóch kolejnych znaków podkreślenia (_). Te nazwy są zarezerwowane dla identyfikatorów generowanych przez kompilator.
Użyj znaczących i opisowych nazw zmiennych, metod i klas.
Preferuj jasność nad zwięzłością.
Użyj PascalCase dla nazw klas i nazw metod.
Użyj camelCase dla parametrów metody i zmiennych lokalnych.
Użyj PascalCase dla nazw stałych, zarówno pól, jak i stałych lokalnych.
Pola wystąpienia prywatnego zaczynają się od podkreślenia (_), a pozostały tekst jest wielbłądowany.
Pola statyczne zaczynają się od s_. Ta konwencja nie jest domyślnym zachowaniem programu Visual Studio ani częścią wytycznych dotyczących projektowania struktury, ale jest konfigurowana w pliku editorconfig.
Unikaj używania skrótów lub akronimów w nazwach, z wyjątkiem powszechnie znanych i akceptowanych skrótów.
Użyj znaczących i opisowych przestrzeni nazw, które są zgodne z odwrotną notacją nazwy domeny.
Wybierz nazwy zestawów, które reprezentują podstawowy cel zestawu.
Unikaj używania nazw jednoliterowych, z wyjątkiem prostych liczników pętli. Ponadto przykłady składni opisujące składnię konstrukcji języka C# często używają następujących nazw jednoliterowych, które są zgodne z konwencją używaną w specyfikacji języka C#. Przykłady składni są wyjątkiem od reguły.
- Służy S do tworzenia struktur C dla klas.
- Użyj M dla metod.
- Użyj dla v zmiennych dla p parametrów.
- Użyj parametrów rref .

Napiwek

Konwencje nazewnictwa, które dotyczą wielkości liter, prefiksów, sufiksów i separatorów wyrazów, można wymusić przy użyciu reguł nazewnictwa stylu kodu.

W poniższych przykładach wskazówki dotyczące elementów oznaczonych public są również stosowane podczas pracy z elementami protected i protected internal , z których wszystkie mają być widoczne dla osób wywołujących zewnętrznych.

Przypadek Pascal

Użyj wielkości liter pascal ("PascalCasing") podczas nazewnictwa typu class, interface, structlub delegate .

public class DataService
{
}

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

public struct ValueCoordinate
{
}

public delegate void DelegateType(string message);

W przypadku nazewnictwa interfaceelementu należy używać wielkości liter w języku pascal oprócz prefiksu nazwy z elementem I. Ten prefiks wyraźnie wskazuje konsumentom, że jest interfaceto .

public interface IWorkerQueue
{
}

Podczas nazewnictwa public elementów członkowskich typów, takich jak pola, właściwości, zdarzenia, należy użyć wielkości liter pascal. Ponadto należy używać wielkości liter dla wszystkich metod i funkcji lokalnych.

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;
        // ...
    }
}

Podczas pisania rekordów pozycyjnych należy użyć wielkości liter dla parametrów, ponieważ są one właściwościami publicznymi rekordu.

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

Aby uzyskać więcej informacji na temat rekordów pozycyjnych, zobacz Składnia pozycyjna definicji właściwości.

Przypadek wielbłąda

Użyj wielkości liter wielbłąda ("camelCasing") podczas nazewnictwa private lub internal pól i prefiksuj je za pomocą _elementu . Użyj wielkości liter wielbłąda podczas nazewnictwa zmiennych lokalnych, w tym wystąpień typu delegata.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Napiwek

Podczas edytowania kodu w języku C#, który jest zgodny z tymi konwencjami nazewnictwa w środowisku IDE obsługującym uzupełnianie instrukcji, wpisywanie _ spowoduje wyświetlenie wszystkich elementów członkowskich o zakresie obiektów.

Podczas pracy z polami static , które są private lub internal, użyj prefiksu s_ i w przypadku statycznego użycia t_wątku .

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

Podczas pisania parametrów metody należy użyć wielkości liter wielbłąda.

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

Aby uzyskać więcej informacji na temat konwencji nazewnictwa języka C#, zobacz styl kodowania zespołu środowiska uruchomieniowego platformy .NET.

Wskazówki dotyczące nazewnictwa parametrów typu

Poniższe wskazówki dotyczą parametrów typu dla parametrów typu ogólnego. Parametry typu to symbole zastępcze argumentów w typie ogólnym lub metodzie ogólnej. Więcej informacji na temat parametrów typu ogólnego można znaleźć w przewodniku programowania w języku C#.

Czy nazwa rodzajowa parametrów typu z nazwami opisowymi, chyba że nazwa pojedynczej litery jest całkowicie objaśniona, a nazwa opisowa nie doda wartości.
```
public interface ISessionChannel<TSession> { /*...*/ }
public delegate TOutput Converter<TInput, TOutput>(TInput from);
public class List<T> { /*...*/ }
```

Rozważ użycie T jako nazwy parametru typu dla typów z jednym typem litery parametru.

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

Do prefiks nazwy parametrów typu opisowego z "T".

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

Rozważ wskazanie ograniczeń umieszczonych na parametrze typu w nazwie parametru. Na przykład ograniczenie ISession parametru może być nazywane .TSession

Reguła analizy kodu CA1715 może służyć do zapewnienia, że parametry typu są odpowiednio nazwane.

Dodatkowe konwencje nazewnictwa

Przykłady, które nie zawierają dyrektyw używających, używają kwalifikacji przestrzeni nazw. Jeśli wiesz, że przestrzeń nazw jest domyślnie importowana w projekcie, nie musisz w pełni kwalifikować nazw z tej przestrzeni nazw. Kwalifikowane nazwy mogą być przerywane po kropki (.), jeśli są zbyt długie dla pojedynczego wiersza, jak pokazano w poniższym przykładzie.
```
var currentPerformanceCounterCategory = new System.Diagnostics.
    PerformanceCounterCategory();
```
Nie musisz zmieniać nazw obiektów utworzonych przy użyciu narzędzi projektanta programu Visual Studio, aby dopasować je do innych wytycznych.