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

  • Статья

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

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

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

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

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

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

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

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

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

<значения типа>

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

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

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

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

Свойство Description Допустимые значения Обязательное поле
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		 No

Примечания

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

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

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

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

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

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

Примечания

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

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

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

Свойство Description
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. Все частные поля ( static или нет) должны underscored применять стиль именования к ним в качестве компилятора error.
  2. Частные поля с staticunderscored стилем именования должны применяться к ним с уровнем 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 правилами именования.

См. также