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

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

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

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

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

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

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

Важно!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Совет

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

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

Pascal case

При именовании типа 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используйте регистр pascal в дополнение к префиксу имени с I. Этот префикс четко указывает потребителям, что это interface.

public interface IWorkerQueue
{
}

При именовании членов public таких типов, как поля, свойства, события, используйте стиль ПаскальКейс. Кроме того, используйте 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 используйте верблюжий стиль ("camelCasing") и добавляйте префикс _. Используйте стиль CamelCase при именовании локальных переменных, включая экземпляры типа делегата.

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>() => 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 можно использовать для обеспечения соответствующего именованности параметров типа.

Дополнительные правила именования

• Примеры, не содержащие с помощью директив, используйте квалификацию пространства имен. Если вы знаете, что пространство имен импортируется по умолчанию в проекте, вам не нужно полностью указать имена из этого пространства имен. Полные имена можно разделить после точки (.), если они слишком длинные для одной строки, как показано в следующем примере.

  var currentPerformanceCounterCategory = new System.Diagnostics.
      PerformanceCounterCategory();
  

• Вам не нужно изменять имена объектов, созданных с помощью средств конструктора Visual Studio, чтобы они соответствовали другим рекомендациям.