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

  • Статья

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

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

Допустимые идентификаторы должны соответствовать следующим правилам.

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

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

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

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

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

  • Имена интерфейсов начинаются с заглавной буквы I.
  • Типы атрибутов заканчиваются словом Attribute.
  • Типы перечисления используют единственное существительное для нефлагов и множественное существительное для флагов.
  • Идентификаторы не должны содержать два последовательных символа подчеркивания (_). Эти имена зарезервированы для идентификаторов, созданных компилятором.
  • Используйте значимые и описательные имена для переменных, методов и классов.
  • Избегайте использования однобуквенных имен, за исключением простых счетчиков циклов. См. исключения для примеров синтаксиса, указанных в следующем разделе.
  • Предпочитайте ясность по поводу краткости.
  • Используйте PascalCase для имен классов и имен методов.
  • Используйте верблюдье Регистр для аргументов метода, локальных переменных и частных полей.
  • Используйте PascalCase для имен констант, как полей, так и локальных констант.
  • Поля частного экземпляра начинаются с подчеркивания (_).
  • Статические поля начинаются с s_. Обратите внимание, что это не поведение Visual Studio по умолчанию, а не часть рекомендаций по проектированию Платформы, но настраиваемое в редакторе.
  • Избегайте использования аббревиаций или акронимов в именах, за исключением широко известных и принятых аббревиаций.
  • Используйте значимые и описательные пространства имен, которые соответствуют нотации обратного доменного имени.
  • Выберите имена сборок, представляющие основную цель сборки.

В примерах, описывающих синтаксис конструкций 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# см. в статье Стиль написания кода на C#.

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

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