Udostępnij za pośrednictwem

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

Identyfikator to nazwa, którą przypisujesz do typu (klasa, interfejs, struktura, delegat lub wyliczenie), członka, zmiennej lub przestrzeni 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ślnikiem (_).
  • Identyfikatory mogą zawierać znaki Unicode litery, znaki cyfr dziesiętnych, znaki łączące Unicode, znaki łączące Unicode, 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 lub Nl), cyfrę (Nd), łączenie (Pc), łączenie (Mn lub Mc) i formatowanie (Cf) kategorii. Wszystko, co jest poza tym zakresem, jest automatycznie zastępowane przy użyciu _. 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 w języku C# używają PascalCase dla nazw typów, przestrzeni nazw i wszystkich publicznych członków. 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 w liczbie pojedynczej dla brakujących flag 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.

  • Prywatne pola instancji zaczynają się od podkreślnika (_), a pozostały tekst jest w notacji camelCase.

  • 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.

    • Użyj S dla struktur, C dla klas.
    • Użyj M dla metod.
    • Użyj v dla zmiennych, a p dla parametrów.
    • Użyj r do parametrów ref.

Wskazówka

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, struct lub 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 interface należy używać stylu PascalCase oraz poprzedzać nazwę I. Ten prefiks wyraźnie wskazuje konsumentom, że to jest interface.

public interface IWorkerQueue
{
}

Podczas nadawania nazw elementom członkowskim typów, takim jak pola, właściwości i zdarzenia, należy używać notacji Pascal. Ponadto należy używać notacji Pascal 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ć notacji pascalowej 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 camel case ("camelCasing") podczas nazewnictwa private lub internal pól i dodaj prefiks _. Użyj camelCase podczas nazewnictwa zmiennych lokalnych, w tym wystąpień typu delegacyjnego.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Wskazówka

Podczas edytowania kodu w języku C#, który jest zgodny z tymi konwencjami nazewnictwa w środowisku IDE obsługującym automatyczne uzupełnianie kodu, wpisanie _ spowoduje wyświetlenie wszystkich elementów członkowskich na poziomie obiektu.

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

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

Podczas pisania parametrów metody należy użyć notacji wielbłądziej.

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#.

  • Nazywaj ogólne parametry typu, używając opisowych nazw, chyba że nazwa jednoliterowa jest całkowicie jednoznaczna i nazwa opisowa nie dodawałaby 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>() => 0;
public delegate bool Predicate<T>(T item);
public struct Nullable<T> where T : struct { /*...*/ }

  • Do nazw parametrow typu opisowego dodaj prefiks "T".

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

  • Rozważ wskazanie ograniczeń umieszczonych na parametrze typu w nazwie parametru. Na przykład parametr ograniczony do ISession może być nazywany 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życia, korzystają z 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. Nazwy kwalifikowane mogą być przerywane po kropce (.), jeśli są zbyt długie na jedną linię, 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.