Правила и соглашения об именовании идентификаторов C#

  • Статья

Идентификатор — это имя, которое вы присваиваете типу (классу, интерфейсу, структуре, делегату или перечислению), члену, переменной или пространству имен.

Правила именования

Допустимые идентификаторы должны соответствовать этим правилам. Компилятор C# выдает ошибку для любого идентификатора, который не соответствует этим правилам:

  • Идентификаторы должны начинаться с буквы или подчеркивания (_).
  • Идентификаторы могут содержать символы букв Юникода, десятичные символы, соединения символов Юникода, объединения символов Юникода или символов форматирования Юникода. Дополнительные сведения о категориях Юникода см. в разделе База данных категорий Юникода.

Вы можете объявить идентификаторы, соответствующие ключевым словам C#, с помощью префикса идентификатора @. Имя @ идентификатора не является частью имени идентификатора. Например, @if объявляет идентификатор с именем if. Эти буквальные идентификаторы предназначены главным образом для взаимодействия с идентификаторами, объявленными в других языках.

Полное определение допустимых идентификаторов см . в статье "Идентификаторы" в спецификации языка C#.

Внимание

Спецификация языка C# допускает только букву (Lu, Ll, Lt, Lm, Lo или Nl), цифру (Nd), подключение (Pc), объединение (Mn или Mc) и категории форматирования (Cf). Все, что находится за пределами, которое автоматически заменено с помощью _. Это может повлиять на определенные символы Юникода.

Соглашения об именах

Помимо правил, соглашения об именах идентификаторов используются во всех API .NET. Эти соглашения обеспечивают согласованность имен, но компилятор не применяет их. Вы можете использовать различные соглашения в проектах.

По соглашению программы C# используют PascalCase для имен типов, пространства имен и всех открытых членов. Кроме того, dotnet/docs команда использует следующие соглашения, принятые из стиля кодирования команды среды выполнения .NET:

  • Имена интерфейсов начинаются с заглавной буквы I.

  • Типы атрибутов заканчиваются словом Attribute.

  • Типы перечисления используют единственное существительное для нефлагов и множественное существительное для флагов.

  • Идентификаторы не должны содержать два последовательных символа подчеркивания (_). Эти имена зарезервированы для идентификаторов, созданных компилятором.

  • Используйте значимые и описательные имена для переменных, методов и классов.

  • Предпочитайте ясность по поводу краткости.

  • Используйте PascalCase для имен классов и имен методов.

  • Используйте верблюдье Регистр для параметров метода и локальных переменных.

  • Используйте PascalCase для имен констант, как полей, так и локальных констант.

  • Поля частного экземпляра начинаются с подчеркивания (_) и оставшийся текст верблюд.

  • Статические поля начинаются с s_. Это соглашение не является поведением Visual Studio по умолчанию, а не частью рекомендаций по проектированию Платформы, но настраивается в editorconfig.

  • Избегайте использования аббревиаций или акронимов в именах, за исключением широко известных и принятых аббревиаций.

  • Используйте значимые и описательные пространства имен, которые соответствуют нотации обратного доменного имени.

  • Выберите имена сборок, представляющие основную цель сборки.

  • Избегайте использования однобуквенных имен, за исключением простых счетчиков циклов. Кроме того, в примерах синтаксиса, описывающих синтаксис конструкций C#, часто используются следующие однобуквные имена, соответствующие соглашению, используемому в спецификации языка C#. Примеры синтаксиса являются исключением из правила.

    • Используется S для структур C для классов.
    • Используется M для методов.
    • Используется v для переменных p для параметров.
    • Используется r для ref параметров.

Совет

Вы можете применять соглашения об именовании, касающиеся буквы, префиксов, суффиксов и разделителей слов с помощью правил именования в стиле кода.

В следующих примерах рекомендации, относящиеся к элементам, помеченным public , также применимы при работе с protected элементами и protected internal элементами, которые предназначены для отображения внешним вызывающим элементам.

Регистр Pascal

Используйте pascal casing (PascalCasing) при именовании class, interfacestructили 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 элементов типов, таких как поля, свойства, события, используйте регистр pascal. Кроме того, используйте pascal casing для всех методов и локальных функций.

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

Совет

При редактировании кода C#, который соответствует соглашениям об именовании в интегрированной среде разработки, поддерживающей завершение операторов, при вводе _ отображаются все элементы области объекта.

При работе с полями static, являющимися private или internal, используйте префикс 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, чтобы привести их в соответствие с другими рекомендациями.