Naamgevingsregels en conventies voor C#-id

Artikel
01/30/2024

Een id is de naam die u toewijst aan een type (klasse, interface, struct, delegate of enum), lid, variabele of naamruimte.

Naamgevingsregels

Geldige id's moeten aan deze regels voldoen. De C#-compiler genereert een fout voor een id die niet aan deze regels voldoen:

Id's moeten beginnen met een letter of onderstrepingsteken (_).
Id's kunnen Unicode-lettertekens, decimale tekens, Unicode-verbindingstekens, Unicode-combinatietekens of Unicode-opmaaktekens bevatten. Zie de Unicode-categoriedatabase voor meer informatie over Unicode-categorieën.

U kunt id's declareren die overeenkomen met C#-trefwoorden met behulp van het @ voorvoegsel op de id. De @ id maakt geen deel uit van de id-naam. Declareert bijvoorbeeld @if een id met de naam if. Deze verbatim-id's zijn voornamelijk bedoeld voor interoperabiliteit met id's die in andere talen zijn gedeclareerd.

Zie het artikel Id's in de C#-taalspecificatie voor een volledige definitie van geldige id's.

Belangrijk

De C#-taalspecificatie staat alleen lettercategorieën (Lu, Ll, Lt, Lm, Lo of Nl), digit (Nd), connecting (Pc), combining (Mn of Mc) en opmaak (Cf) toe. Alles buiten dat automatisch wordt vervangen met behulp van _. Dit kan van invloed zijn op bepaalde Unicode-tekens.

Naamconventies

Naast de regels worden conventies voor id-namen gebruikt in de .NET-API's. Deze conventies bieden consistentie voor namen, maar de compiler dwingt ze niet af. U kunt verschillende conventies in uw projecten gebruiken.

C#-programma's gebruiken PascalCase standaard voor het typen van namen, naamruimten en alle openbare leden. Daarnaast gebruikt het dotnet/docs team de volgende conventies, die zijn overgenomen uit de coderingsstijl van het .NET Runtime-team:

Interfacenamen beginnen met een hoofdletter I.
Kenmerktypen eindigen met het woord Attribute.
Enum-typen gebruiken een enkel zelfstandig naamwoord voor nonflags en een meervouds zelfstandig naamwoord voor vlaggen.
Id's mogen geen twee opeenvolgende onderstrepingstekens (_) bevatten. Deze namen zijn gereserveerd voor door compiler gegenereerde id's.
Gebruik zinvolle en beschrijvende namen voor variabelen, methoden en klassen.
Geef de voorkeur aan duidelijkheid over kortheid.
Gebruik PascalCase voor klassenamen en methodenamen.
Gebruik camelCase voor methodeparameters en lokale variabelen.
Gebruik PascalCase voor constante namen, zowel velden als lokale constanten.
Privé-exemplaarvelden beginnen met een onderstrepingsteken (_) en de resterende tekst is camelCased.
Statische velden beginnen met s_. Deze conventie is niet het standaardgedrag van Visual Studio en maakt geen deel uit van de ontwerprichtlijnen voor framework, maar kan wel worden geconfigureerd in editorconfig.
Vermijd het gebruik van afkortingen of acroniemen in namen, met uitzondering van algemeen bekende en geaccepteerde afkortingen.
Gebruik zinvolle en beschrijvende naamruimten die de notatie van de omgekeerde domeinnaam volgen.
Kies assemblynamen die het primaire doel van de assembly vertegenwoordigen.
Vermijd het gebruik van namen met één letter, met uitzondering van eenvoudige lustellers. Ook gebruiken syntaxisvoorbeelden die de syntaxis van C#-constructies beschrijven vaak de volgende namen met één letter die overeenkomen met de conventie die wordt gebruikt in de C#-taalspecificatie. Voorbeelden van syntaxis zijn een uitzondering op de regel.
- Gebruiken S voor structs, C voor klassen.
- Gebruiken M voor methoden.
- Gebruiken v voor variabelen, p voor parameters.
- Gebruiken r voor ref parameters.

Tip

U kunt naamconventies afdwingen die betrekking hebben op hoofdlettergebruik, voorvoegsels, achtervoegsels en woordscheidingstekens met codestijl.

In de volgende voorbeelden zijn richtlijnen met betrekking tot gemarkeerde public elementen ook van toepassing bij het werken met protected en protected internal elementen, die allemaal zichtbaar zijn voor externe bellers.

Pascal zaak

Gebruik pascalbehuizing ('PascalCasing') bij het benoemen van een class, interfaceof structdelegate type.

public class DataService
{
}

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

public struct ValueCoordinate
{
}

public delegate void DelegateType(string message);

Wanneer u een naam aangeeft interface, gebruikt u Pascal-behuizing naast het voorvoegsel van de naam met een I. Dit voorvoegsel geeft duidelijk aan dat het een interface.

public interface IWorkerQueue
{
}

Bij het public benoemen van leden van typen, zoals velden, eigenschappen, gebeurtenissen, gebruikt u pascal casing. Gebruik ook pascalbehuizing voor alle methoden en lokale functies.

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;
        // ...
    }
}

Wanneer u positionele records schrijft, gebruikt u pascal-hoofdletters voor parameters, omdat ze de openbare eigenschappen van de record zijn.

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

Zie Positionele syntaxis voor eigenschapsdefinitie voor meer informatie over positionele records.

Kameel geval

Gebruik kameelbehuizing ('camelCasing') bij het benoemen private of internal velden en voorvoegsel met _. Gebruik kameelbehuizing bij het benoemen van lokale variabelen, inclusief exemplaren van een gemachtigdentype.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Tip

Wanneer u C#-code bewerkt die volgt op deze naamconventies in een IDE die voltooiing van de instructie ondersteunt, _ worden alle leden van het objectbereik weergegeven.

Wanneer u werkt met static velden die dat zijn private of internal, gebruikt u het s_ voorvoegsel en voor statisch threadgebruik t_.

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

Gebruik kameelbehuizing bij het schrijven van methodeparameters.

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

Zie de coderingsstijl van het .NET Runtime-team voor meer informatie over C#-naamconventies.

Richtlijnen voor naamgeving van parameters typen

De volgende richtlijnen zijn van toepassing op typeparameters voor algemene typeparameters. Typeparameters zijn de tijdelijke aanduidingen voor argumenten in een algemeen type of een algemene methode. Meer informatie over algemene typeparameters vindt u in de C#-programmeerhandleiding.

Geef algemene typeparameters een naam met beschrijvende namen, tenzij een enkele letter volledig verklarend is en een beschrijvende naam geen waarde zou toevoegen.
```
public interface ISessionChannel<TSession> { /*...*/ }
public delegate TOutput Converter<TInput, TOutput>(TInput from);
public class List<T> { /*...*/ }
```

Overweeg het gebruik T als de parameternaam van het type voor typen met één lettertypeparameter.

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

Geef voorvoegsel beschrijvende type parameternamen met 'T'.

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

Overweeg om beperkingen aan te geven die zijn geplaatst voor een typeparameter in de naam van de parameter. Een parameter die is beperkt, ISession kan bijvoorbeeld worden aangeroepen TSession.

De codeanalyseregel CA1715 kan worden gebruikt om ervoor te zorgen dat typeparameters de juiste naam hebben.

Extra naamconventies

Voorbeelden die geen instructies bevatten, gebruiken naamruimtekwalificaties. Als u weet dat een naamruimte standaard in een project wordt geïmporteerd, hoeft u de namen van die naamruimte niet volledig in aanmerking te komen. Gekwalificeerde namen kunnen worden verbroken na een punt (.) als ze te lang zijn voor één regel, zoals wordt weergegeven in het volgende voorbeeld.
```
var currentPerformanceCounterCategory = new System.Diagnostics.
    PerformanceCounterCategory();
```
U hoeft niet de namen te wijzigen van objecten die zijn gemaakt met de Visual Studio Designer-hulpprogramma's om ze aan andere richtlijnen te laten voldoen.

Delen via

Naamgevingsregels en conventies voor C#-id