Regras de nomenclatura de estilo de código
No arquivo .editorconfig, você pode definir convenções de nomenclatura para seus elementos de código de linguagem de programação do .NET, como classes, propriedades e métodos, e como o compilador ou o IDE devem impor essas convenções. Por exemplo, você pode especificar que um membro público que não esteja em letras maiúsculas deve ser tratado como um erro do compilador ou que, se um campo privado não começar com _
, um aviso de build deverá ser emitido.
Especificamente, você pode definir uma regra de nomenclatura, que consiste em três partes:
- O grupo de símbolos ao qual a regra se aplica; por exemplo, membros públicos ou campos privados.
- O estilo de nomenclatura a ser associado à regra; por exemplo, que o nome deve estar em letras maiúsculas ou começar com um sublinhado.
- O nível de severidade da mensagem quando os elementos de código incluídos no grupo de símbolos não seguem o estilo de nomenclatura.
Sintaxe geral
Para definir qualquer uma das entidades acima (regra de nomenclatura, grupo de símbolos ou estilo de nomenclatura), defina uma ou mais propriedades usando a seguinte sintaxe:
<kind>.<entityName>.<propertyName> = <propertyValue>
Todas as configurações de propriedade de um determinado kind
e entityName
compõem essa definição de entidade específica.
Cada propriedade só deve ser definida uma vez, mas algumas configurações permitem vários valores separados por vírgula.
A ordem das propriedades não é importante.
Valores de <tipo>
O <tipo> especifica o tipo de entidade que está sendo definido (regra de nomenclatura, grupo de símbolos ou estilo de nomenclatura) e deve ser um dos seguintes:
Para definir uma propriedade de | Use o valor de <tipo> | Exemplo |
---|---|---|
Regra de nomenclatura | dotnet_naming_rule |
dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion |
Grupo de símbolos | dotnet_naming_symbols |
dotnet_naming_symbols.interface.applicable_kinds = interface |
Estilo de nomenclatura | dotnet_naming_style |
dotnet_naming_style.pascal_case.capitalization = pascal_case |
<entityName>
<entityName> é um nome descritivo que você escolhe que associa várias configurações de propriedade a uma única definição. Por exemplo, as propriedades a seguir produzem duas definições de grupo de símbolos, interface
e types
, cada uma delas tem duas propriedades definidas.
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> e <propertyValue>
Cada tipo de entidade (regra de nomenclatura, grupo de símbolos ou estilo de nomenclatura) tem suas próprias propriedades compatíveis, conforme descrito nas seções a seguir.
Propriedades do grupo de símbolos
Você pode definir as propriedades a seguir para grupos de símbolos, para limitar os símbolos incluídos no grupo. Para especificar vários valores para uma única propriedade, separe os valores com uma vírgula.
Propriedade | Descrição | Valores permitidos | Obrigatório |
---|---|---|---|
applicable_kinds |
Tipos de símbolos no grupo 1 | * (use este valor para especificar todos os símbolos)namespace class struct interface enum property method field event delegate parameter type_parameter local local_function |
Sim |
applicable_accessibilities |
Níveis de acessibilidade dos símbolos no grupo | * (use este valor para especificar todos os níveis de acessibilidade)public internal ou friend private protected protected_internal ou protected_friend private_protected local (para símbolos definidos em um método) |
Sim |
required_modifiers |
Corresponder apenas aos símbolos com todos os modificadores 2 especificados | abstract ou must_inherit async const readonly static ou shared 3 |
No |
Observações:
- Atualmente, não há suporte para membros de tupla no
applicable_kinds
. - O grupo de símbolos corresponde a todos os modificadores na propriedade
required_modifiers
. Se você omitir essa propriedade, nenhum modificador específico será obrigatório para uma correspondência. Isso significa que os modificadores de um símbolo não têm efeito sobre a opção de aplicar essa regra ou não. - Se o grupo tiver
static
oushared
na propriedaderequired_modifiers
, o grupo também incluirá símbolosconst
, pois eles são implicitamentestatic
/Shared
. No entanto, se você não quiser que a regra de nomenclaturastatic
se aplique aos símbolosconst
, crie uma regra de nomenclatura com um grupo de símbolos deconst
. A nova regra terá precedência de acordo com a ordem de regra. class
inclui registros em C#.
Propriedades do estilo de nomenclatura
Um estilo de nomenclatura define as convenções que você deseja impor com a regra. Por exemplo:
- Coloca em maiúsculas com
PascalCase
. - Começa com
m_
. - Termina com
_g
. - Separa palavras com
__
.
Você pode definir as seguintes propriedades para um estilo de nomenclatura:
Propriedade | Descrição | Valores permitidos | Obrigatório |
---|---|---|---|
capitalization |
Estilo de capitalização das palavras no símbolo | pascal_case camel_case first_word_upper all_upper all_lower |
Sim1 |
required_prefix |
Deve começar com esses caracteres | No | |
required_suffix |
Deve terminar com esses caracteres | No | |
word_separator |
Palavras no símbolo precisam ser separadas com esse caractere | No |
Observações:
- É necessário especificar um estilo de uso de maiúsculas como parte do seu estilo de nomenclatura; caso contrário, o estilo de nomenclatura poderá ser ignorado.
Propriedades da regra de nomenclatura
Todas as propriedades da regra de nomenclatura são obrigatórias para que uma regra entre em vigor.
Propriedade | Descrição |
---|---|
symbols |
O nome de um grupo de símbolos definido em outro lugar; a regra de nomenclatura será aplicada aos símbolos desse’ grupo. |
style |
O nome do estilo de nomenclatura que deve ser associado a essa regra; o estilo é definido em outro lugar. |
severity |
Define a severidade com a qual a regra de nomenclatura será imposta. Defina o valor associado como um dos níveis de severidade disponíveis.1 |
Observações:
- A especificação de severidade em uma regra de nomenclatura só é respeitada em IDEs de desenvolvimento, como o Visual Studio. Essa configuração não é reconhecida pelos compiladores C# ou VB; portanto, não é respeitada durante o build. Para impor regras de estilo de nomenclatura no build, você deve definir a severidade usando a configuração de severidade da regra de código. Para saber mais, confira este problema do GitHub.
Ordem das regras
Não importa a ordem na qual as regras de nomenclatura são definidas em um arquivo EditorConfig. As regras de nomenclatura são ordenadas automaticamente de acordo com a definição das próprias regras. Regras mais específicas sobre acessibilidades, modificadores e símbolos prevalecem sobre as regras menos específicas. Se houver sobreposição entre regras ou se a ordenação de regras causar problemas, você poderá dividir a interseção das duas regras em uma nova regra que prevalece sobre as regras mais amplas das quais foi derivada. Para exemplos, consulte Exemplo: Estratégias de nomenclatura sobrepostas e Exemplo: const
o modificador inclui static
e readonly
.
A extensão do Serviço de Linguagem do EditorConfig pode analisar um arquivo EditorConfig e relatar casos em que a ordenação de regra no arquivo é diferente da que o compilador usará no tempo de execução.
Observação
Se você estiver usando uma versão do Visual Studio anterior ao Visual Studio 2019, as regras de nomenclatura deverão ser ordenadas da mais específica para a menos específica no arquivo EditorConfig. A primeira regra encontrada que pode ser aplicada é a única regra que é aplicada. No entanto, se houver várias propriedades de regras com o mesmo nome, a propriedade mais recente encontrada com esse nome terá precedência. Confira mais informações em Precedência e hierarquia de arquivos.
Exemplo: estratégias de nomenclatura sobrepostas
Considere as duas regras de nomenclatura a seguir:
- Os métodos gerais são PascalCase.
- Os métodos assíncronos terminam com
"Async"
.
Para métodos public async
, não é óbvio qual regra prevalece. Você pode criar uma nova regra para métodos public async
e especificar exatamente a nomenclatura.
Exemplo: const
o modificador inclui static
e readonly
Considere as duas regras de nomenclatura a seguir:
- Os campos constantes são PascalCase.
- Os campos não públicos
static
são s_camelCase.
A regra 2 é mais específica e tem prevalência, portanto, todos os campos constantes não públicos são s_camelCase. Para resolver o problema, você pode definir uma regra de interseção: campos constantes não públicos são PascalCase.
Estilos de nomenclatura padrão
Se você não especificar regras de nomenclatura personalizadas, os seguintes estilos padrão serão usados:
Para classes, estruturas, enumerações, propriedades e eventos com acessibilidade, o estilo de nomenclatura padrão é Pascal Case.
Para interfaces com acessibilidade, o estilo de nomenclatura padrão é Pascal Case com o prefixo I obrigatório.
ID da regra de código: IDE1006 (Naming rule violation)
Todas as opções de nomenclatura têm ID IDE1006
de regra e título Naming rule violation
. Você pode configurar a severidade das violações de nomenclatura globalmente em um arquivo EditorConfig com a seguinte sintaxe:
dotnet_diagnostic.IDE1006.severity = <severity value>
O valor da severidade deve ser warning
ou error
para ser imposto no build. Para obter todos os valores de severidade possíveis, confira nível de severidade.
Exemplo: capitalização de membro público
O arquivo .editorconfig a seguir contém uma convenção de nomenclatura que especifica que propriedades públicas, métodos, campos, eventos e delegados marcados com readonly
devem sempre ser escritos com maiúsculas. A convenção de nomenclatura especifica vários tipos de símbolo aos quais aplicar a regra, usando uma vírgula para separar os valores.
[*.{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
Exemplo: campos de instância privada com sublinhado
Este snippet do arquivo .editorconfig impõe que os campos de instância privada devem começar com _
. Se essa convenção não for seguida, o IDE a tratará como um erro do compilador. Os campos estáticos privados são ignorados.
Como você só pode definir um grupo de símbolos com base nos identificadores que ele tem (por exemplo, static
ou readonly
) e não pelos identificadores que ele não tem (por exemplo, um campo de instância, pois ele não tem static
), você precisa definir duas regras de nomenclatura:
- Todos os campos privados,
static
ou não, devem ter o estilo de nomenclaturaunderscored
aplicado a eles como um compiladorerror
. - Campos privados com
static
devem ter o estilo de nomenclaturaunderscored
aplicado a eles com um nível de severidade denone
; em outras palavras, ignore esse caso.
[*.{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
Este exemplo também demonstra que as definições de entidade podem ser reutilizadas. O estilo de nomenclatura underscored
é usado pelas regras de nomenclatura private_fields_underscored
e private_static_fields_none
.