Partager via

Règles de nommage de style de code

  • Article

Dans votre fichier .editorconfig, vous pouvez définir des conventions d’affectation de noms pour vos éléments de code de langage de programmation .NET, comme les classes, les propriétés et les méthodes, et comment le compilateur ou l’IDE doit appliquer ces conventions. Par exemple, vous pouvez spécifier qu’un membre public qui n’est pas mis en majuscules doit être traité comme une erreur du compilateur, ou que si un champ privé ne commence pas par _, un avertissement de build doit être émis.

Plus précisément, vous pouvez définir une règle de nommage, qui se compose de trois parties :

  • Le groupe de symboles auquel la règle s’applique, par exemple les membres publics ou les champs privés.
  • Le style de nommage à associer à la règle, par exemple, en indiquant que le nom doit commencer par une majuscule ou un trait de soulignement.
  • Niveau de gravité du message lorsque les éléments de code inclus dans le groupe de symboles ne suivent pas le style de nommage.

Syntaxe générale

Pour définir l’une des entités ci-dessus (une règle de nommage, un groupe de symboles ou un style de nommage), définissez une ou plusieurs propriétés à l’aide de la syntaxe suivante :

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

Tous les paramètres de propriété d’un kind et d’un entityName donnés composent cette définition d’entité spécifique.

Chaque propriété ne doit être définie qu’une seule fois, mais certains paramètres autorisent les valeurs multiples séparées par des virgules.

L’ordre des propriétés n’est pas important.

Valeurs pour <kind>

<kind> spécifie le type d’entité défini (règle de nommage, groupe de symboles ou style de nommage) et doit avoir l’une des valeurs suivantes :

Pour définir une propriété pour Utiliser la valeur <kind> Exemple
Règle de nommage dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
Groupe de symboles dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
Style de nommage dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<nomEntité>

<entityName> est un nom descriptif que vous choisissez qui associe plusieurs paramètres de propriété à une seule définition. Par exemple, les propriétés suivantes produisent deux définitions de groupe de symboles, interface et types, chacune ayant deux propriétés définies.

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

Chaque type d’entité (règle de nommage, groupe de symboles ou style de nommage) a ses propres propriétés prises en charge, comme décrit dans les sections suivantes.

Propriétés du groupe de symboles

Vous pouvez définir les propriétés suivantes pour les groupes de symboles afin de limiter les symboles inclus dans le groupe. Pour spécifier plusieurs valeurs pour une seule propriété, séparez les valeurs par une virgule.

Propriété Description Valeurs autorisées Obligatoire
applicable_kinds Types de symboles dans le groupe 1 * (Utilisez cette valeur pour spécifier tous les symboles.)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Oui
applicable_accessibilities Niveaux d’accessibilité des symboles dans le groupe * (Utilisez cette valeur pour spécifier tous les niveaux d’accessibilité.)
public
internal ou friend
private
protected
protected_internal ou protected_friend
private_protected
local (pour les symboles définis dans une méthode)		 Oui
required_modifiers Faire correspondre uniquement les symboles avec tous les modificateurs spécifiés 2 abstract ou must_inherit
async
const
readonly
static ou shared 3		 Non

Remarques :

  1. Les membres de tuple ne sont actuellement pas pris en charge dans applicable_kinds.
  2. Le groupe de symboles correspond à tous les modificateurs de la propriété required_modifiers. Si vous omettez cette propriété, aucun modificateur spécifique n’est requis pour une correspondance. Cela signifie que les modificateurs d’un symbole n’ont aucun effet sur l’application ou non de cette règle.
  3. Si votre groupe a static ou shared dans la propriété required_modifiers, le groupe inclut également des symboles const, car ils sont implicitement static/Shared. Toutefois, si vous ne souhaitez pas que la règle de nommage static s’applique aux symboles const, vous pouvez créer une règle de nommage avec un groupe de symboles de const. La nouvelle règle est prioritaire d’après l’ordre des règles.
  4. class inclut des enregistrements C#.

Propriétés de style de nommage

Un style de nommage définit les conventions que vous souhaitez appliquer avec la règle. Par exemple :

  • Mise en majuscules avec PascalCase
  • Commence par m_
  • Finit par _g
  • Séparer les mots avec __

Vous pouvez définir les propriétés suivantes pour un style de nommage :

Propriété Description Valeurs autorisées Obligatoire
capitalization Style de mise en majuscules pour les mots dans le symbole pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Oui1
required_prefix Doit commencer par ces caractères Non
required_suffix Doit se terminer par ces caractères Non
word_separator Les mots du symbole doivent être séparés par ce caractère Non

Remarques :

  1. Vous devez spécifier un style de mise en majuscules dans le cadre de votre style de nommage, sans quoi votre style de nommage risque d’être ignoré.

Propriétés de la règle de nommage

Toutes les propriétés de règle de nommage sont requises pour qu’une règle prenne effet.

Propriété Description
symbols Le nom d’un groupe de symboles défini ailleurs ; la règle de nommage sera appliquée aux symboles de ce groupe
style Le nom du style de nommage qui doit être associé à cette règle ; le style est défini ailleurs
severity Définit la gravité avec laquelle appliquer la règle de nommage. Définissez la valeur associée sur l’un des niveaux de gravité disponibles. 1

Remarques :

  1. La spécification de gravité dans une règle de nommage est uniquement respectée à l’intérieur des IDE de développement, comme Visual Studio. Ce paramètre n’est pas compris par les compilateurs C# ou VB, et n’est donc pas respecté pendant la génération. Pour appliquer des règles de style de nommage lors de la compilation, vous devez définir la gravité à l’aide de la configuration de la gravité des règles de code. Pour plus d’informations, consultez ce problème GitHub.

Ordre des règles

L’ordre dans lequel les règles de nommage sont définies dans un fichier EditorConfig n’a pas d’importance. Les règles de nommage sont automatiquement triées en fonction des définitions des règles elles-mêmes. Des règles plus spécifiques concernant les accessibilités, les modificateurs et les symboles sont prioritaires sur les règles moins spécifiques. S’il existe un chevauchement entre des règles ou si l’ordre des règles provoque des problèmes, vous pouvez corriger cette intersection des deux règles avec une nouvelle règle qui prend la priorité sur les règles plus larges dont elle a été dérivée. Pour obtenir des exemples, consultez Exemple : Stratégies de nommage qui se chevauchent et Exemple : le modificateur const inclut static et readonly.

L’extension du service de langage EditorConfig peut analyser un fichier EditorConfig et signaler les cas où l’ordre des règles du fichier est différent de celui utilisé par le compilateur au moment de l’exécution.

Notes

Si vous utilisez une version de Visual Studio antérieure à Visual Studio 2019, les règles de nommage doivent être classées de la plus spécifique à la moins spécifique dans le fichier EditorConfig. La première règle applicable rencontrée est la seule règle appliquée. Toutefois, s’il existe plusieurs propriétés de règle portant le même nom, la propriété la plus récemment trouvée portant ce nom est prioritaire. Pour plus d’informations, consultez Priorité et hiérarchie des fichiers.

Exemple : stratégies de nommage qui se chevauchent

Considérez les deux règles de nommage suivantes :

  1. Les méthodes publiques sont en CassePascal.
  2. Les méthodes asynchrones se terminent par "Async".

Pour les méthodes public async, il n’est pas facile de déterminer quelle règle est prioritaire. Vous pouvez créer une règle pour les méthodes public async et spécifier exactement le nommage.

Exemple : le modificateur const inclut static et readonly

Considérez les deux règles de nommage suivantes :

  1. Les champs de constante sont en CassePascal.
  2. Les champs non publics static sont en s_casseMixte.

La règle 2 étant plus spécifique et prioritaire, tous les champs de constante non publics sont en s_casseMixte. Pour résoudre le problème, vous pouvez définir une règle d’intersection : les champs de constante non publics sont en CassePascal.

Styles de dénomination par défaut

Si vous ne spécifiez pas de règles de dénomination personnalisées, les styles par défaut suivants sont utilisés :

  • Pour les classes, structures, énumérations, méthodes, propriétés et événements avec tout niveau d’accessibilité, le style de dénomination par défaut est la casse Pascal.

  • Pour les interfaces avec tout niveau d’accessibilité, le style de dénomination par défaut est la casse Pascal avec le préfixe I requis.

ID de règle de code : IDE1006 (Naming rule violation)

Toutes les options de nommage ont l’ID de règle IDE1006 et le titre Naming rule violation. Vous pouvez configurer la gravité des violations de nommage globalement dans un fichier EditorConfig avec la syntaxe suivante :

dotnet_diagnostic.IDE1006.severity = <severity value>

La valeur de gravité doit être warning ou error pour être appliquée à la compilation. Pour toutes les valeurs de gravité possibles, consultez Niveau de gravité.

Exemple : mise en majuscules des membres publics

Le fichier .editorconfig suivant contient une convention de nommage qui spécifie que les propriétés publiques, les méthodes, les champs, les événements et les délégués marqués comme readonly doivent être mis en majuscules. Cette convention de nommage spécifie plusieurs types de symboles auxquels appliquer la règle, en utilisant une virgule pour séparer les valeurs.

[*.{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

Exemple : Champs d’instance privés avec trait de soulignement

Cet extrait de fichier .editorconfig applique le fait que les champs d’instance privée doivent commencer par _ ; si cette convention n’est pas suivie, l’IDE traite cela comme une erreur du compilateur. Les champs statiques privés sont ignorés.

Étant donné que vous ne pouvez définir qu’un groupe de symboles en fonction des identificateurs qu’il possède (par exemple, static ou readonly), et non par les identificateurs qu’il n’a pas (par exemple, un champ d’instance, car il n’a pas de static), vous devez définir deux règles de nommage :

  1. Tous les champs privés, static ou non, doivent avoir le style de nommage underscored appliqué en tant que error du compilateur.
  2. Les champs privés avec static doivent avoir le style de nommage underscored appliqué avec un niveau de gravité de none ; en d’autres termes, la casse est ignorée.
[*.{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

Cet exemple montre également que les définitions d’entité peuvent être réutilisées. Le style de nommage underscored est utilisé à la fois par les règles de nommage private_fields_underscored et private_static_fields_none.

Voir aussi