Partilhar via

Regras de nomenclatura em estilo de código

  • Artigo

Em seu arquivo .editorconfig , você pode definir convenções de nomenclatura para seus elementos de código da linguagem de programação .NET, como classes, propriedades e métodos, e como o compilador ou IDE deve impor essas convenções. Por exemplo, você pode especificar que um membro público que não esteja em maiúsculas deve ser tratado como um erro de compilador ou que, se um campo privado não começar com um _, um aviso de compilação deve 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, de que o nome deve ser maiúsculo ou começar com um sublinhado.
  • O nível de gravidade 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 — uma regra de nomenclatura, um grupo de símbolos ou um estilo de nomenclatura — defina uma ou mais propriedades usando a seguinte sintaxe:

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

Todas as configurações de propriedade para um determinado kind e entityName compõem essa definição de entidade específica.

Cada propriedade deve ser definida apenas uma vez, mas algumas configurações permitem vários valores separados por vírgula.

A ordem das propriedades não é importante.

<valores de tipo>

<sort> especifica qual tipo de entidade está sendo definido — regra de nomenclatura, grupo de símbolos ou estilo de nomenclatura — e deve ser um dos seguintes:

Para definir uma propriedade para 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

<nome_da_entidade>

<entityName> é um nome descritivo escolhido por você que associa várias configurações de propriedade em uma única definição. Por exemplo, as propriedades a seguir produzem duas definições de grupo de símbolos e types, cada uma com duas propriedades definidasinterface.

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 suportadas, conforme descrito nas seções a seguir.

Propriedades do grupo de símbolos

Você pode definir as seguintes propriedades para grupos de símbolos, para limitar quais símbolos são incluídos no grupo. Para especificar vários valores para uma única propriedade, separe os valores com uma vírgula.

Property Description Valores permitidos Necessá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 dentro de um método)		 Sim
required_modifiers Corresponder apenas símbolos com todos os modificadores especificados 2 abstract ou must_inherit
async
const
readonly
static ou shared 3		 Não

Notas:

  1. Atualmente, os membros do Tuple não são suportados no applicable_kinds.
  2. O grupo de símbolos corresponde a required_modifiers todos os modificadores na propriedade. Se você omitir essa propriedade, nenhum modificador específico será necessário para uma correspondência. Isso significa que os modificadores de um símbolo não têm efeito sobre se essa regra é ou não aplicada.
  3. Se o seu grupo tiver static ou shared na propriedade, o grupo também incluirá const símbolos porque eles estão implicitamenteSharedstatic/ .required_modifiers No entanto, se não quiser que a static regra de nomenclatura se aplique aos const símbolos, você pode criar uma nova regra de nomenclatura com um grupo de símbolos de const. A nova regra terá precedência de acordo com a ordem das regras.
  4. class inclui registros C#.

Nomeando propriedades de estilo

Um estilo de nomenclatura define as convenções que você deseja impor com a regra. Por exemplo:

  • Capitalize com PascalCase
  • Começa com m_
  • Termina com _g
  • Separe as palavras com __

Você pode definir as seguintes propriedades para um estilo de nomenclatura:

Property Description Valores permitidos Necessário
capitalization Estilo de maiúsculas para palavras dentro do símbolo pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Sim1
required_prefix Deve começar com estes caracteres Não
required_suffix Deve terminar com estes caracteres Não
word_separator As palavras dentro do símbolo precisam ser separadas com este caractere Não

Notas:

  1. Você deve especificar um estilo de maiúsculas como parte do seu estilo de nomenclatura, caso contrário, seu estilo de nomenclatura pode ser ignorado.

Propriedades da regra de nomenclatura

Todas as propriedades da regra de nomenclatura são necessárias para que uma regra entre em vigor.

Property Description
symbols O nome de um grupo de símbolos definido em outro lugar; A regra de nomenclatura será aplicada aos símbolos deste grupo
style O nome do estilo de nomenclatura que deve ser associado a esta regra; o estilo é definido em outro lugar
severity Define a severidade com a qual impor a regra de nomenclatura. Defina o valor associado para um dos níveis de gravidade disponíveis.1

Notas:

  1. A especificação de gravidade dentro de uma regra de nomenclatura só é respeitada dentro de IDEs de desenvolvimento, como o Visual Studio. Essa configuração não é compreendida pelos compiladores C# ou VB, portanto, não é respeitada durante a compilação. Para impor regras de estilo de nomenclatura na compilação, você deve, em vez disso, definir a severidade usando a configuração de severidade da regra de código. Para obter mais informações, consulte este problema do GitHub.

Ordem das regras

A ordem na qual as regras de nomenclatura são definidas em um arquivo EditorConfig não importa. As regras de nomenclatura são ordenadas automaticamente de acordo com as definições das próprias regras. Regras mais específicas relativas a acessibilidades, modificadores e símbolos têm precedência sobre regras menos específicas. Se houver sobreposição entre regras ou se a ordenação da regra causar problemas, você pode dividir a interseção das duas regras em uma nova regra que tenha precedência sobre as regras mais amplas das quais ela foi derivada. Para obter exemplos, consulte Exemplo: estratégias de nomenclatura sobrepostas e Exemplo: const modificador inclui static e readonly.

A extensão EditorConfig Language Service pode analisar um arquivo EditorConfig e relatar casos em que a ordem de ordenação no arquivo é diferente do que o compilador usará em tempo de execução.

Nota

Se você estiver usando uma versão do Visual Studio anterior ao Visual Studio 2019, as regras de nomenclatura devem ser ordenadas do mais específico para o menos específico no arquivo EditorConfig. A primeira regra encontrada que pode ser aplicada é a única regra que é aplicada. No entanto, se houver várias propriedades de regra com o mesmo nome, a propriedade encontrada mais recentemente com esse nome terá precedência. Para obter mais informações, consulte Hierarquia e precedência de arquivos.

Exemplo: Estratégias de nomenclatura sobrepostas

Considere as duas regras de nomenclatura a seguir:

  1. Os métodos públicos são PascalCase.
  2. Os métodos assíncronos terminam com "Async".

Para public async os métodos, não é óbvio qual regra tem precedência. Você pode criar uma nova regra para public async métodos e especificar a nomenclatura exatamente.

Exemplo: const 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 precedência, pelo que 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 nenhuma regra de nomenclatura personalizada, os seguintes estilos padrão serão usados:

  • Para classes, structs, enumerações, propriedades, métodos e eventos com qualquer acessibilidade, o estilo de nomenclatura padrão é Pascal case.

  • Para interfaces com qualquer acessibilidade, o estilo de nomenclatura padrão é Pascal case com um prefixo necessário de I.

ID da regra de código: IDE1006 (Naming rule violation)

Todas as opções de nomenclatura têm ID IDE1006 e título Naming rule violationda regra. Você pode configurar a gravidade das violações de nomenclatura globalmente em um arquivo EditorConfig com a seguinte sintaxe:

dotnet_diagnostic.IDE1006.severity = <severity value>

O valor de severidade deve ser warning ou a ser imposto na compilaçãoerror. Para todos os valores de gravidade possíveis, consulte Nível de gravidade.

Exemplo: capitalização de membro público

O seguinte arquivo .editorconfig contém uma convenção de nomenclatura que especifica que as propriedades públicas, métodos, campos, eventos e delegados marcados readonly devem ser capitalizados. Esta 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 trecho do arquivo .editorconfig impõe que os campos de instância privada devem começar com um _; se essa convenção não for seguida, o IDE irá tratá-lo como um erro de 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 porque não tem static), você precisa definir duas regras de nomenclatura:

  1. Todos os campos privados — static ou não — devem ter o underscored estilo de nomenclatura aplicado a eles como um compilador error.
  2. Campos privados com static devem ter o underscored estilo de nomenclatura aplicado a eles com um nível de severidade de none; em outras palavras, ignore este 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 underscored estilo de nomenclatura é usado pelas private_fields_underscored regras de nomenclatura e private_static_fields_none nomenclatura.

Consulte também