Правила именования для стиля кода

  • Статья

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

В частности, можно определить правило именования, состоящее из трех частей:

  • Группа символов, к которой применяется это правило, например открытые элементы или закрытые поля.
  • Стиль именования, связываемый с этим правилом, например обязательное использование прописных букв или использование символа подчеркивания в качестве первого символа имени.
  • Уровень серьезности сообщения, когда элементы кода, включенные в группу символов, не соответствуют стилю именования.

Общий синтаксис

Чтобы определить любую из указанных выше сущностей (правило именования, группу символов или стиль именования), задайте одно или несколько свойств с помощью следующего синтаксиса:

<kind>.<entityName>.<propertyName> = <propertyValue>

Все параметры свойств для заданного kind и entityName составляют это определение конкретной сущности.

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

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

<значения kind>

<kind> указывает, какой тип сущности определяется (правило именования, группа символов или стиль именования) и должен быть одним из следующих:

Для чего задается свойство <Использование значения типа> Пример
Правило именования dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
Группа символов dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
Стиль именования dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<entityName>

<entityName> — это выбранное описательное имя, которое связывает несколько параметров свойств в одном определении. Например, следующие свойства создают два определения группы символов (interface и types) и устанавливают для каждого из них два свойства.

dotnet_naming_symbols.interface.applicable_kinds = interface
dotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected

dotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum, delegate
dotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected

<propertyName> и <propertyValue>

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

Свойства группы символов

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

Свойство Описание Допустимые значения Обязательно
applicable_kinds Типы символов в группе 1 * (используйте это значение, чтобы указать все символы)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Да
applicable_accessibilities Уровни доступности для символов в группе * (используйте это значение, чтобы указать все уровни доступа)
public
internal либо friend
private
protected
protected_internal или protected_friend
private_protected
local (для символов, определенных в методе)		 Да
required_modifiers Соответствует только тем символам, у которых есть все указанные модификаторы 2 abstract либо must_inherit
async
const
readonly
static или shared3		 Нет

Примечания.

  1. Элементы кортежа в настоящее время поддерживаются только в applicable_kinds.
  2. Группа символов сопоставляет все модификаторы в свойстве required_modifiers. Если вы опустите это свойство, для сопоставления не требуются конкретные модификаторы. Это означает, что модификаторы символов не оказывают влияния на применение этого правила.
  3. Если группа имеет значение static или shared в свойстве required_modifiers, в нее будут включены также символы const, так как они неявно являются static/Shared. Но если вы не хотите применять правило именования static к символам const, вы можете создать новое правило именования для группы символов const. Новое правило будет иметь приоритет в соответствии с порядком правил.
  4. class включает записи (record) C#.

Свойства стиля именования

Стиль именования определяет соглашения, которые будут применяться к правилу. Например:

  • Использование прописных букв PascalCase
  • Начинается с m_
  • Заканчивается на _g
  • Разделение слов с помощью __

Для стиля именования можно задать следующие свойства:

Свойство Описание Допустимые значения Обязательно
capitalization Стиль применения прописных букв для слов в пределах символа pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Да1
required_prefix Должно начинаться с этих символов Нет
required_suffix Должно заканчиваться этими символами Нет
word_separator Слова внутри символа должны разделяться этим символом Нет

Примечания.

  1. Указать регистр букв для стиля именования обязательно, в противном случае ваш стиль может игнорироваться.

Свойства правила именования

Чтобы правило вступило в силу, должны быть указаны все свойства правила именования.

Свойство Описание
symbols Имя группы символов, определенное в другом месте; Правило именования будет применено к символам в этой группе
style Имя стиля именования, которое должно быть связано с этим правилом; стиль определяется в другом месте
severity Задает серьезность, с которой будет применяться это правило именования. Задает для сопоставленного значения один из доступных уровней серьезности1

Примечания.

  1. Спецификация серьезности в правиле именования учитывается только в интегрированных средах разработки, таких как Visual Studio. Компиляторы C# или VB не понимают этот параметр и не учитывают его при сборке. Чтобы применить правила стиля именования к сборке, уровень серьезности следует задать с помощью конфигурации серьезности в правиле кода. См. дополнительные сведения на сайте GitHub.

Порядок правил

Порядок определения правил в файле EditorConfig не имеет значения. Правила именования автоматически упорядочиваются в соответствии с определениями самих правил. Более конкретные правила, касающиеся специальных возможностей, модификаторов и символов, имеют приоритет над менее конкретными правилами. Если правила перекрываются или порядок правил вызывает проблемы, можно разбить пересечение двух правил на новое правило, которое имеет приоритет над более широкими правилами, от которых оно было получено. Примеры см. в разделах Пример. Перекрывающиеся стратегии именования и Пример: const модификатор включает static и readonly.

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

Примечание

Если вы используете версию Visual Studio, более раннюю, чем Visual Studio 2019, правила именования должны быть упорядочены от наиболее конкретных к наименее конкретным в файле EditorConfig. Применяться будет только первое обнаруженное правило. Но при наличии множества свойств правил с одним и тем же именем приоритет будет иметь последнее обнаруженное свойство с таким именем. См. подробнее об иерархии файлов и приоритетности.

Пример. Перекрывающиеся стратегии именования

Рассмотрим следующие два правила именования:

  1. Открытые методы — PascalCase.
  2. Асинхронные методы заканчиваются на "Async".

Для public async методов не ясно, какое правило имеет приоритет. Можно создать новое правило для public async методов и точно указать именование.

Пример: const модификатор включает static и readonly

Рассмотрим следующие два правила именования:

  1. Поля констант — PascalCase.
  2. Поля, не являющиеся открытыми static , s_camelCase.

Правило 2 более специфично и имеет приоритет, поэтому все поля констант, не являющиеся открытыми, s_camelCase. Чтобы устранить эту проблему, можно определить правило пересечения: поля не являются открытыми константами PascalCase.

Стили именования по умолчанию

Если вы не укажете никаких пользовательских правил именования, применяются следующие стили по умолчанию:

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

  • Для интерфейсов со специальными возможностями по умолчанию используется стиль именования Pascal с обязательным префиксом I.

Идентификатор правила кода: IDE1006 (Naming rule violation)

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

dotnet_diagnostic.IDE1006.severity = <severity value>

Серьезность должна иметь значение warning или error, чтобы принудительно применяться при сборке. Все возможные значения серьезности перечислены на странице об уровнях серьезности.

Пример. Заглавная буква открытого члена

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

[*.{cs,vb}]

# Defining the 'public_symbols' symbol group
dotnet_naming_symbols.public_symbols.applicable_kinds           = property,method,field,event,delegate
dotnet_naming_symbols.public_symbols.applicable_accessibilities = public
dotnet_naming_symbols.public_symbols.required_modifiers         = readonly

# Defining the 'first_word_upper_case_style' naming style
dotnet_naming_style.first_word_upper_case_style.capitalization = first_word_upper

# Defining the 'public_members_must_be_capitalized' naming rule, by setting the
# symbol group to the 'public symbols' symbol group,
dotnet_naming_rule.public_members_must_be_capitalized.symbols  = public_symbols
# setting the naming style to the 'first_word_upper_case_style' naming style,
dotnet_naming_rule.public_members_must_be_capitalized.style    = first_word_upper_case_style
# and setting the severity.
dotnet_naming_rule.public_members_must_be_capitalized.severity = suggestion

Пример. Поля частного экземпляра с символом подчеркивания

Этот фрагмент файла .editorconfig принудительно указывает, что поля частного _экземпляра должны начинаться с ; если это соглашение не соблюдается, интегрированная среда разработки будет рассматривать его как ошибку компилятора. Закрытые статические поля игнорируются.

Так как группу символов можно определить только на основе имеющихся у нее идентификаторов (например, static или readonly), а не по идентификаторам, которых у нее нет (например, по полю экземпляра staticиз-за отсутствия ), необходимо определить два правила именования:

  1. Все закрытые поля должны staticunderscored иметь стиль именования, применяемый к ним в качестве компилятора error.
  2. Закрытые поля с static должны иметь underscored стиль именования, применяемый к ним с уровнем noneсерьезности ; иными словами, игнорируйте этот случай.
[*.{cs,vb}]

# Define the 'private_fields' symbol group:
dotnet_naming_symbols.private_fields.applicable_kinds = field
dotnet_naming_symbols.private_fields.applicable_accessibilities = private

# Define the 'private_static_fields' symbol group
dotnet_naming_symbols.private_static_fields.applicable_kinds = field
dotnet_naming_symbols.private_static_fields.applicable_accessibilities = private
dotnet_naming_symbols.private_static_fields.required_modifiers = static

# Define the 'underscored' naming style
dotnet_naming_style.underscored.capitalization = pascal_case
dotnet_naming_style.underscored.required_prefix = _

# Define the 'private_fields_underscored' naming rule
dotnet_naming_rule.private_fields_underscored.symbols = private_fields
dotnet_naming_rule.private_fields_underscored.style = underscored
dotnet_naming_rule.private_fields_underscored.severity = error

# Define the 'private_static_fields_none' naming rule
dotnet_naming_rule.private_static_fields_none.symbols = private_static_fields
dotnet_naming_rule.private_static_fields_none.style = underscored
dotnet_naming_rule.private_static_fields_none.severity = none

В этом примере также показано, что определения сущностей можно использовать повторно. Стиль underscored именования используется как правилами именования, private_fields_underscored так и private_static_fields_none .

См. также