Règles et conventions de nommage des identificateurs C#

Un identificateur est le nom que vous assignez à un type (classe, interface, struct, délégué ou enum), un membre, une variable ou un espace de noms.

Règles de nommage

Les identificateurs valides doivent suivre les règles suivantes. Le compilateur C# génère une erreur pour tout identificateur qui ne suit pas ces règles :

• Les identificateurs doivent commencer par une lettre ou un trait de soulignement (_).
• Les identificateurs peuvent contenir des lettres Unicode, des nombres décimaux, des caractères de connexion Unicode, des caractères de combinaison Unicode ou des caractères de mise en forme Unicode. Pour plus d’informations sur les catégories Unicode, consultez la Base de données des catégories Unicode.

Vous pouvez déclarer des identificateurs qui correspondent à des mots clés C# en utilisant le préfixe @ sur l’identificateur. @ ne fait pas partie du nom de l’identificateur. Par exemple, @if déclare un identificateur nommé if. Ces identificateurs textuels sont destinés principalement à assurer l’interopérabilité avec les identificateurs déclarés dans d’autres langages.

Pour une définition complète des identificateurs valides, consultez la rubrique Identificateurs dans la spécification du langage C#.

Conventions d'attribution d'un nom

En plus des règles, les conventions de noms d’identificateurs sont utilisées dans les API .NET. Ces conventions garantissent la cohérence pour les noms, mais le compilateur ne les applique pas. Vous êtes libre d’utiliser des conventions différentes dans vos projets.

Par convention, les programmes C# utilisent PascalCase pour les noms de types, les espaces de noms et tous les membres publics. En outre, l’équipe dotnet/docs utilise les conventions suivantes, adoptées à partir du style de codage de l’équipe .NET Runtime :

• Les noms d’interfaces commencent par un I majuscule.

• Les types d’attribut finissent par le mot Attribute.

• Les types enum utilisent un nom singulier pour les non-indicateurs et un nom pluriel pour les indicateurs.

• Les identificateurs ne doivent pas contenir deux traits de soulignement consécutifs (_). Ces noms sont réservés aux identificateurs générés par le compilateur.

• Utilisez des noms utiles et descriptifs pour les variables, les méthodes et les classes.

• Préférez la clarté à la concision.

• Utilisez la casse Pascal pour les noms de classes et de méthode.

• Utilisez le format camelCase pour les paramètres de méthode et les variables locales.

• Utilisez la casse Pascal pour les noms de constantes, à la fois pour les champs et les constantes locales.

• Les champs d’instance privée commencent par un trait de soulignement (_) et le texte restant est au format camelCase.

• Les champs statiques commencent par s_. Cette convention n’est pas le comportement par défaut de Visual Studio et ne fait pas partie des instructions de conception d’infrastructure, mais il est configurable dans editorconfig.

• Évitez d’utiliser des abréviations ou des acronymes dans des noms, à l’exception d’abréviations bien connues et acceptées.

• Utilisez des espaces de noms explicites et descriptifs qui respectent la notation de nom de domaine inverse.

• Choisissez des noms d’assembly qui représentent l’objectif principal de l’assembly.

• Évitez d’utiliser des noms à lettres uniques, sauf pour les compteurs à boucles simples. De plus, les exemples qui décrivent la syntaxe des constructions C# utilisent souvent les noms à lettres uniques suivants qui correspondent à la convention utilisée dans la spécification du langage C#. Les exemples de syntaxe sont une exception à la règle.

  • Utilisez S pour les structs et C pour les classes.
  • Utilisez M pour les méthodes.
  • Utilisez v pour les variables et p pour les paramètres.
  • Utilisez r pour les paramètres ref.

Dans les exemples suivants, l’aide relative aux éléments marqués public s’applique également lors de l’utilisation d’éléments protected et protected internal, qui sont tous destinés à être visibles par des appelants externes.

Casse Pascal

Utilisez la casse Pascal (« PascalCasing ») lorsque vous nommez un type class, interface, struct ou delegate.

public class DataService
{
}

public record PhysicalAddress(
    string Street,
    string City,
    string StateOrProvince,
    string ZipCode);

public struct ValueCoordinate
{
}

public delegate void DelegateType(string message);

Lorsque vous nommez un interface, utilisez la casse Pascal en plus d’ajouter le préfixe I au nom. Ce préfixe indique clairement aux consommateurs qu’il s’agit d’une interface.

public interface IWorkerQueue
{
}

Lorsque vous nommez des membres public de types, tels que des champs, des propriétés et des événements, utilisez la casse Pascal. Utilisez également la casse Pascal pour toute méthode et fonction locale.

public class ExampleEvents
{
    // A public field, these should be used sparingly
    public bool IsValid;

    // An init-only property
    public IWorkerQueue WorkerQueue { get; init; }

    // An event
    public event Action EventProcessing;

    // Method
    public void StartEventProcessing()
    {
        // Local function
        static int CountQueueItems() => WorkerQueue.Count;
        // ...
    }
}

Lors de l’écriture d’enregistrements positionnels, utilisez la casse Pascal pour les paramètres, car ils sont les propriétés publiques de l’enregistrement.

public record PhysicalAddress(
    string Street,
    string City,
    string StateOrProvince,
    string ZipCode);

Pour plus d’informations sur les enregistrements positionnels, consultez Syntaxe positionnelle pour la définition de propriété.

Casse mixte

Utilisez la casse camel (« camelCasing ») lors du nommage des champs private ou internal et ajoutez-leur un préfixe avec _. Utilisez la casse camel lors du nommage de variables locales, y compris les instances d’un type délégué.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Lorsque vous utilisez des champs static qui sont private ou internal, utilisez le préfixe s_ et pour le thread static, utilisez t_.

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

Lors de l’écriture de paramètres de méthode, utilisez la casse mixte.

public T SomeMethod<T>(int someNumber, bool isValid)
{
}

Pour plus d’informations sur les conventions d’affectation de noms C#, consultez le style de codage de l’équipe .NET Runtime.

Recommandations concernant le nom des paramètres de type

Les instructions suivantes s’appliquent aux paramètres de type sur les paramètres de type générique. Les paramètres de type sont des espaces réservés pour les arguments dans un type générique ou dans une méthode générique. Vous pouvez en savoir plus sur les paramètres de type générique dans le guide de programmation C#.

• Nommez les paramètres de type générique avec des noms descriptifs, sauf si un nom composé d’une seule lettre est suffisamment évocateur et qu’un nom descriptif n’apporte rien de plus.

  public interface ISessionChannel<TSession> { /*...*/ }
  public delegate TOutput Converter<TInput, TOutput>(TInput from);
  public class List<T> { /*...*/ }
  

• Envisagez d’utiliser T comme nom de paramètre de type pour les types ayant un paramètre de type avec une seule lettre.

  public int IComparer<T>() { return 0; }
  public delegate bool Predicate<T>(T item);
  public struct Nullable<T> where T : struct { /*...*/ }
  

• Préfixez les noms des paramètres de type descriptifs avec « T ».

  public interface ISessionChannel<TSession>
  {
      TSession Session { get; }
  }
  

• Pensez à indiquer les contraintes placées sur un paramètre de type dans le nom de paramètre. Par exemple, un paramètre limité à ISession peut être appelé TSession.

La règle d’analyse du code CA1715 vérifie que les paramètres de type sont correctement nommés.

Conventions supplémentaires d’affectation de noms

• Dans les exemples qui ne comprennent pas de directives, utilisez les qualifications d’espace de noms. Si vous savez qu'un espace de noms est importé par défaut dans un projet, vous n'êtes pas obligé de qualifier entièrement les noms à partir de cet espace de noms. Les noms qualifiés peuvent être interrompus après un point (.) s'ils sont trop longs pour tenir sur une seule ligne, comme indiqué dans l'exemple suivant.

  var currentPerformanceCounterCategory = new System.Diagnostics.
      PerformanceCounterCategory();
  

• Vous n'avez pas à modifier les noms des objets qui ont été créés à l'aide des outils du concepteur Visual Studio pour les rendre conformes aux autres directives.