Regras de nomenclatura de estilo de código

  • Artigo

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

Observações:

  1. Atualmente, não há suporte para membros de tupla no applicable_kinds.
  2. 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.
  3. Se o grupo tiver static ou shared na propriedade required_modifiers, o grupo também incluirá símbolos const, pois eles são implicitamente static/Shared. No entanto, se você não quiser que a regra de nomenclatura static se aplique aos símbolos const, crie uma regra de nomenclatura com um grupo de símbolos de const. A nova regra terá precedência de acordo com a ordem de regra.
  4. 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:

  1. É 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:

  1. 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:

  1. Os métodos gerais são PascalCase.
  2. 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:

  1. Os campos constantes são PascalCase.
  2. 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:

  1. Todos os campos privados, static ou não, devem ter o estilo de nomenclatura underscored aplicado a eles como um compilador error.
  2. Campos privados com static devem ter o estilo de nomenclatura underscored aplicado a eles com um nível de severidade de none; 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.

Confira também