Regras de nomenclatura de estilo de código

No .editorconfig arquivo, você pode definir as regras de nomenclatura que especificam e impõem como elementos de código de linguagem de programação .net, — como classes, propriedades e métodos, — devem ser nomeados. Por exemplo, você pode especificar que os membros públicos devem estar em letras maiúsculas ou que os campos particulares devem começar com _ .

Uma regra de nomenclatura tem três componentes:

  • O grupo de símbolos ao qual a regra se aplica, por exemplo, membros públicos ou campos particulares.
  • 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.
  • A severidade para impor a Convenção.

Primeiro, você deve especificar o grupo de símbolos e o estilo de nomenclatura e dar a cada um deles um título. Em seguida, especifique a regra de nomenclatura, que vincula tudo em conjunto.

Sintaxe geral

Para definir uma regra de nomenclatura, um grupo de símbolos ou um estilo de nomenclatura, defina uma ou mais propriedades usando a seguinte sintaxe:

<kind>.<title>.<propertyName> = <propertyValue>

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.

<kind>

<kind> Especifica qual tipo de elemento está sendo definido como — regra de nomenclatura, grupo de símbolos ou estilo de nomenclatura — e deve ser um dos seguintes:

Para definir uma propriedade para Usar o <kind> valor 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

Cada tipo de — regra de nomenclaturade definição, grupo de símbolosou estilo de nomenclatura — tem suas próprias propriedades com suporte, conforme descrito nas seções a seguir.

<title>

<title> é um nome descritivo que você escolhe 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 interface de símbolos 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

Propriedades da regra de nomenclatura

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

Propriedade Descrição
symbols O título de um grupo de símbolos; a regra de nomenclatura será aplicada aos símbolos neste grupo
style O título do estilo de nomenclatura que deve ser associado a esta regra
severity Define a severidade com a qual impor a regra de nomenclatura. Defina o valor associado como um dos níveis de severidadedisponíveis. 1

Observações:

  1. A especificação de severidade dentro de uma regra de nomenclatura só é respeitada dentro de IDEs de desenvolvimento, como 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 definir a severidade usando a configuração de severidade de regra de código. Para saber mais, confira este problema do GitHub.

Propriedades do grupo de símbolos

Você pode definir as seguintes propriedades para grupos de símbolos, para limitar quais símbolos estão 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 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
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 required_modifiers 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 a opção de aplicar essa regra ou não.
  3. Se o grupo tiver static ou shared na required_modifiers propriedade, o grupo também incluirá const símbolos, pois eles são implicitamente static / Shared . No entanto, se você não quiser que a static regra de nomenclatura se aplique a const símbolos, poderá criar uma nova regra de nomenclatura com um grupo de símbolos de const .
  4. class inclui registros C#.

Propriedades de estilo de nomenclatura

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

  • Colocar em maiúsculas com PascalCase
  • Começa com m_
  • Termina com _g
  • Separar 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 de 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 No
required_suffix Deve terminar com estes caracteres No
word_separator As palavras dentro do símbolo precisam ser separadas com este 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.

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 a definição das próprias regras. A extensão de serviço de linguagem EditorConfig pode analisar um arquivo EditorConfig e casos de relatório em que a ordenação de regra no arquivo é diferente do que o compilador usará em tempo de execução.

Observação

se você estiver usando uma versão do Visual Studio anterior ao Visual Studio 2019 versão 16,2, 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.

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 é o caso do Pascal.

  • 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 de regra e título Naming rule violation . Você pode configurar a severidade de 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 error ser imposto na compilação. Para todos os valores de severidade possíveis, consulte nível de severidade.

Exemplo

O arquivo .editorconfig a seguir contém uma convenção de nomenclatura que especifica que propriedades públicas, métodos, campos, eventos e delegados devem sempre ser escritos com maiúsculas. Observe que 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

Confira também