Reglas de nomenclatura del estilo de código

  • Artículo

En el archivo .editorconfig se pueden definir convenciones de nomenclatura para los elementos de código del lenguaje de programación .NET, como clases, propiedades y métodos, y cómo debe aplicar el compilador o el IDE esas convenciones. Por ejemplo, se podría especificar que un miembro público que no esté en mayúsculas se trate como un error del compilador, o que si un campo privado no comienza por _, se emita una advertencia de compilación.

En concreto, se puede definir una regla de nomenclatura, que consta de tres partes:

  • El grupo de símbolos al que se aplica la regla, por ejemplo, los miembros públicos o los campos privados.
  • El estilo de nomenclatura que se va a asociar a la regla, por ejemplo, que el nombre debe escribirse en mayúsculas o empezar con un guion bajo.
  • El nivel de gravedad del mensaje cuando los elementos de código incluidos en el grupo de símbolos no siguen el estilo de nomenclatura.

Sintaxis general

Para definir cualquiera de las entidades anteriores, una regla de nomenclatura, un grupo de símbolos o un estilo de nomenclatura, establezca una o varias propiedades con la sintaxis siguiente:

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

Todos los valores de propiedad de un determinado elemento kind y entityName componen esa definición de entidad específica.

Cada propiedad solo se debe establecer una vez, pero algunas opciones de configuración admiten varios valores separados por comas.

El orden de las propiedades no es importante.

Valores <kind>

<kind> especifica qué tipo de entidad se está definiendo, regla de nomenclatura, grupo de símbolos o estilo de nomenclatura, y debe ser uno de los siguientes:

Para establecer una propiedad para Use el valor <kind> Ejemplo
Regla 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> es un nombre descriptivo que se elige y asocia varios valores de propiedad en una única definición. Por ejemplo, las siguientes propiedades generan dos definiciones de grupo de símbolos, interface y types, y cada una tiene dos propiedades establecidas.

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

Cada tipo de entidad, regla de nomenclatura, grupo de símbolos o estilo de nomenclatura, tiene sus propias propiedades compatibles, como se explica en las secciones siguientes.

Propiedades del grupo de símbolos

Puede establecer las siguientes propiedades para los grupos de símbolos, a fin de limitar qué símbolos se incluyen en el grupo. Para especificar varios valores para una sola propiedad, separe los valores con una coma.

Propiedad Descripción Valores permitidos Obligatorio
applicable_kinds Tipos de símbolos del grupo 1 * (use este valor para especificar todos los símbolos)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Sí
applicable_accessibilities Niveles de accesibilidad de los símbolos del grupo * (use este valor para especificar todos los niveles de accesibilidad)
public
internal o friend
private
protected
protected_internal o protected_friend
private_protected
local (para los símbolos definidos dentro de un método)		 Sí
required_modifiers Solo coinciden los símbolos con todos los modificadores especificados 2 abstract o must_inherit
async
const
readonly
static o shared3		 No

Notas:

  1. Actualmente no se admiten miembros de tupla en applicable_kinds.
  2. El grupo de símbolos coincide con todos los modificadores de la propiedad required_modifiers. Si se omite esta propiedad, no se necesitan modificadores específicos para una coincidencia. Esto significa que los modificadores de un símbolo no influyen positiva o negativamente en la aplicación de esta regla.
  3. Si el grupo tiene static o shared en la propiedad required_modifiers, el grupo también incluirá símbolos const porque son static/Shared de forma implícita. Sin embargo, si no desea que la regla de nomenclatura static se aplique a los símbolos const, puede crear una regla de nomenclatura con un grupo de símbolos de const. La nueva regla tendrá prioridad según el orden de las reglas.
  4. class incluye registros de C#.

Propiedades del estilo de nomenclatura

Un estilo de nomenclatura define las convenciones que desea aplicar a la regla. Por ejemplo:

  • Poner PascalCase en mayúsculas
  • Empieza por m_
  • Termina por _g
  • Separar palabras con __

Puede establecer las siguientes propiedades de un estilo de nomenclatura:

Propiedad Descripción Valores permitidos Obligatorio
capitalization Estilo de uso de mayúsculas para las palabras contenidas en el símbolo pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Sí1
required_prefix Debe comenzar con estos caracteres No
required_suffix Debe terminar con estos caracteres No
word_separator Las palabras contenidas en el símbolo deben estar separadas con este carácter No

Notas:

  1. Debe especificar un estilo de uso de mayúsculas como parte del estilo de nomenclatura; en caso contrario, es posible que el estilo de nomenclatura se ignore.

Propiedades de la regla de nomenclatura

Todas las propiedades de las reglas de nomenclatura son necesarias para que una regla surta efecto.

Propiedad Descripción
symbols Nombre de un grupo de símbolos definido en cualquier otro lugar; la regla de nomenclatura se aplica a los símbolos de este grupo
style Nombre del estilo de nomenclatura que se debe asociar a esta regla; el estilo se define en cualquier otro lugar
severity Establece la gravedad con la que se va a aplicar la regla de nomenclatura. Establezca el valor asociado en uno de los niveles de gravedad disponibles.1

Notas:

  1. La especificación de la gravedad dentro de una regla de nomenclatura solo se respeta dentro de los IDE de desarrollo, como Visual Studio. Los compiladores de C# o VB no entienden esta configuración, por lo que no se respeta durante la compilación. Para aplicar reglas de estilo de nomenclatura a la compilación, debe establecer la gravedad mediante la configuración de la gravedad de la regla de código. Para obtener más información, vea este problema de GitHub.

Orden de las reglas

No importa el orden en el que se definan las reglas de nomenclatura de un archivo EditorConfig. Las reglas de nomenclatura se ordenan automáticamente según las definiciones de las propias reglas. Las reglas más específicas sobre accesibilidad, modificadores y símbolos tienen prioridad sobre las reglas menos específicas. Si hay superposición entre reglas o si la ordenación de reglas provoca problemas, puede dividir la intersección de las dos reglas en una nueva regla que tenga prioridad sobre las reglas más amplias de las que se derivaba. Para obtener ejemplos, vea Ejemplo: Estrategias de nomenclatura superpuestas y Ejemplo: el modificador const incluye static y readonly.

La extensión de servicio de lenguaje de EditorConfig puede analizar un archivo EditorConfig y notificar los casos en los que el orden de las reglas del archivo es diferente al que va a usar el compilador en tiempo de ejecución.

Nota

Si utiliza una versión de Visual Studio anterior a Visual Studio 2019, las reglas de nomenclatura deben ordenarse de la más específica a la menos específica en el archivo EditorConfig. La primera regla encontrada que se puede aplicar es la única que se aplica. Sin embargo, si hay varias propiedades de regla con el mismo nombre, la prioridad la tiene la última propiedad encontrada con ese nombre. Para más información, consulte Prioridad y jerarquía de los archivos.

Ejemplo: Estrategias de nomenclatura superpuestas

Tenga en cuenta las dos reglas de nomenclatura siguientes:

  1. Los métodos públicos son PascalCase.
  2. Los métodos asincrónicos terminan con "Async".

Para los métodos public async, no es obvio qué regla tiene prioridad. Puede crear una nueva regla para los métodos public async y especificar exactamente la nomenclatura.

Ejemplo: el modificador const incluye static y readonly

Tenga en cuenta las dos reglas de nomenclatura siguientes:

  1. Los campos constantes son PascalCase.
  2. Los campos no públicos static son s_camelCase.

La regla 2 es más específica y tiene prioridad, por lo que todos los campos constantes no públicos son s_camelCase. Para resolver el problema, puede definir una regla de intersección: los campos constantes no públicos son PascalCase.

Estilos de nomenclatura predeterminados

Si no especifica ninguna regla de nomenclatura personalizada, se utilizan los siguientes estilos predeterminados:

  • Para clases, estructuras, enumeraciones, propiedades, métodos y eventos con cualquier accesibilidad, el estilo de nomenclatura predeterminado es Pascal Case.

  • Para interfaces con cualquier accesibilidad, el estilo de nomenclatura predeterminado es Pascal Case con el prefijo necesario I.

Identificador de regla de código: IDE1006 (Naming rule violation)

Todas las opciones de nomenclatura tienen el identificador de regla IDE1006 y el título Naming rule violation. Puede configurar la gravedad de las infracciones de nomenclatura globalmente en un archivo EditorConfig con la siguiente sintaxis:

dotnet_diagnostic.IDE1006.severity = <severity value>

El valor de gravedad debe ser warning o error para que se aplique en la compilación. Para consultar todos los valores de gravedad posibles, vea Nivel de gravedad.

Ejemplo: Uso de mayúsculas en un miembro público

El archivo .editorconfig siguiente contiene una convención de nomenclatura que especifica que las propiedades, los métodos, los campos, los eventos y los delegados públicos que estén marcados como readonly deben escribirse en mayúsculas. Esta convención de nomenclatura especifica varios tipos de símbolo a los que aplicar la regla, con una coma para separar los 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

Ejemplo: Campos de instancia privados con subrayado

Este fragmento de código del archivo .editorconfig exige que los campos de instancia privados comiencen por _; si no se sigue esa convención, el IDE lo trata como un error del compilador. Se omiten los campos estáticos privados.

Dado que solo puede definir un grupo de símbolos basado en los identificadores que tiene (por ejemplo, static o readonly) y no por los identificadores que no tiene (por ejemplo, un campo de instancia porque no tiene static), debe definir dos reglas de nomenclatura:

  1. Todos los campos privados (static o no) deben tener aplicado el estilo de nomenclatura underscored como un compilador error.
  2. Los campos privados con static deben tener aplicado el estilo de nomenclatura underscored con un nivel de gravedad de none; es decir, omita 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

En este ejemplo también se muestra que se pueden reutilizar las definiciones de entidad. El estilo de nomenclatura underscored lo usan las reglas de nomenclatura private_fields_underscored y private_static_fields_none.

Vea también