C#-azonosító elnevezési szabályai és konvenciók

Az azonosító egy típushoz (osztályhoz, felülethez, szerkezethez, delegálthoz vagy számhoz), taghoz, változóhoz vagy névtérhez rendelt név.

Ez a cikk az érvényes C#-azonosítók alapvető szabályait és a konzisztens, professzionális kódíráshoz használt elnevezési konvenciókat ismerteti.

Elnevezési szabályok

Az érvényes azonosítóknak követniük kell ezeket a szabályokat. A C#-fordító hibát okoz minden olyan azonosítónál, amely nem követi az alábbi szabályokat:

• Az azonosítóknak betűvel vagy aláhúzásjellel (_) kell kezdődniük.
• Az azonosítók tartalmazhatnak Unicode betűkaraktereket, tizedes számjegyeket, Unicode összekötő karaktereket, Unicode kombináló karaktereket vagy Unicode formázási karaktereket. További információ a Unicode-kategóriákról: Unicode-kategóriaadatbázis.

A C# kulcsszavaknak megfelelő azonosítókat az azonosító @ előtagjának használatával deklarálhatja. A @ nem része az azonosító nevének. Például @if deklarál egy ifnevű azonosítót. Ezek a szó szerinti azonosítók elsősorban a más nyelveken deklarált azonosítókkal való együttműködésre használhatók.

Az érvényes azonosítók teljes definícióját a C# nyelvspecifikációAzonosítók című cikkben találja.

Fontos

A C# nyelvspecifikációs csak betűkategóriákat (Lu, Ll, Lt, Lm vagy Nl), számjegyet (Nd), csatlakozást (Pc), kombinálást (Mn vagy Mc) és formázási (Cf) kategóriákat engedélyez. Bármi, ami azon kívül van, automatikusan a _-re cserélődik le. Ez hatással lehet bizonyos Unicode-karakterekre.

Elnevezési konvenciók

A szabályok mellett az azonosítónevekre vonatkozó konvenciók is használhatók a .NET API-kban. Ezek a konvenciók egységességet biztosítanak a nevekhez, de a fordítóprogram nem kényszeríti ki őket. A projektekben különböző konvenciókat használhat.

A C#-programok konvenció szerint PascalCase használnak típusnevekhez, névterekhez és minden nyilvános taghoz. Emellett a dotnet/docs csapat a .NET futtatókörnyezeti csapat kódolási stílusának a következő konvenciók használatát használja:

• A felületnevek nagybetűvel kezdődnek I.

• Az attribútumtípusok a Attributeszóval végződnek.

• A felsorolási típusok a nem jelölőkhöz egyes számú főnevet, a jelölőkhöz többes számú főnevet használnak.

• Az azonosítók nem tartalmazhatnak két egymást követő aláhúzásjelet (_) karaktert. Ezek a nevek a fordító által létrehozott azonosítók számára vannak fenntartva.

• Használjon értelmes és leíró neveket változókhoz, metódusokhoz és osztályokhoz.

• Inkább az egyértelműséget, mint a rövidséget.

• A PascalCase használata osztálynevekhez és metódusnevekhez.

• A camelCase metódusparaméterekhez és helyi változókhoz használható.

• A PascalCase használatával konstansneveket, mezőket és helyi állandókat is használhat.

• A privát példány mezők alsó vonallal (_) kezdődnek, a fennmaradó szöveg pedig camelCase formátumú.

• A statikus mezők s_kezdődnek. Ez a konvenció nem az alapértelmezett Visual Studio-viselkedés, és nem is része a keretrendszer tervezési irányelveinek, hanem konfigurálható az editorconfig.

• Ne használjon rövidítéseket vagy rövidítéseket a nevekben, kivéve a széles körben ismert és elfogadott rövidítéseket.

• Használjon értelmes és leíró névtereket, amelyek a fordított tartománynév jelölését követik.

• Válassza ki a szerelvény elsődleges célját képviselő szerelvényneveket.

• Kerülje az egybetűs nevek használatát, kivéve az egyszerű hurokszámlálókat. Emellett a C#-szerkezetek szintaxisát leíró szintaxis-példák gyakran az alábbi egybetűs neveket használják, amelyek megfelelnek a C# nyelvspecifikációjábanhasznált konvenciónak. A szintaxis példái kivételt képeznek a szabály alól.

  • A S használata strukturáláshoz, C osztályokhoz.
  • Metódusokhoz használja a M.
  • Változókhoz v, paraméterekhez p.
  • Használja a r-t a ref paraméterekhez.

Borravaló

A nagybetűkkel, előtagokkal, utótagokkal és szóelválasztókkal kapcsolatos elnevezési konvenciók kikényszeríthetők kódstílus-elnevezési szabályokhasználatával.

Az alábbi példákban a public megjelölt elemekre vonatkozó útmutatás az protected és protected internal elemek használatakor is alkalmazható, amelyek mindegyike külső hívó számára látható.

Pascal-eset

Pascal casing ("PascalCasing") használata class, interface, structvagy delegate típus elnevezéséhez.

public class DataService
{
}

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

public struct ValueCoordinate
{
}

public delegate void DelegateType(string message);

A interfaceelnevezésekor használja a Pascal-case írásmódot, valamint lássa el a nevet egy Ielőtaggal. Ez az előtag egyértelműen jelzi a felhasználóknak, hogy ez egy interface.

public interface IWorkerQueue
{
}

Ha public típusú tagokat, például mezőket, tulajdonságokat, eseményeket nevesít, használjon pascal casingot. Emellett használjon Pascal esetet minden metódushoz és helyi függvényhez.

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

Pozíciórekordok írásakor pascal casingot használjon a paraméterekhez, mivel azok a rekord nyilvános tulajdonságai.

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

A pozíciórekordokkal kapcsolatos további információkért lásd tulajdonságdefinícióspozíciószintaxisát.

camelCase

Használjon "camelCasing"-et a private vagy internal mezők elnevezéséhez, és előtagként adja meg a _-t. Helyi változók elnevezéséhez, beleértve a delegate típusú példányokat is, használjon camel case-t.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Borravaló

Amikor az utasítás-kiegészítést támogató IDE-ben a fenti elnevezési konvencióknak megfelelő C#-kódot szerkeszti, a _ beírása megjeleníti az objektum hatókörébe tartozó összes tagot.

Ha staticprivate vagy internalmezőkkel dolgozik, használja a s_ előtagot, és a szál statikus mezők esetében használja a t_-et.

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

Metódusparaméterek írásakor használja a camel case-t.

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

Elsődleges konstruktorparaméterek

Az elsődleges konstruktorparaméterek elnevezése a deklarált típustól függ:

• A class és struct típusok esetén: Használjon camel case-t, amely konzisztens más metódusparaméterekkel.

  public class DataService(IWorkerQueue workerQueue, ILogger logger)
  {
      public void ProcessData()
      {
          // Use the parameters directly
          logger.LogInformation("Processing data");
          workerQueue.Enqueue("data");
      }
  }
  

  public struct Point(double x, double y)
  {
      public double Distance => Math.Sqrt(x * x + y * y);
  }
  

• Típusok esetén record : Használja a Pascal-burkolatot, mivel a paraméterek nyilvános tulajdonságokká válnak.

  public record Person(string FirstName, string LastName);
  public record Address(string Street, string City, string PostalCode);
  

További információ az elsődleges konstruktorokról: Elsődleges konstruktorok.

További információ a C#-elnevezési konvenciókról a .NET Runtime csapat kódolási stílusánaktalálható.

Típusparaméter elnevezési irányelvei

Az alábbi irányelvek az általános típusparaméterek típusparamétereire vonatkoznak. A típusparaméterek az általános vagy általános metódus argumentumainak helyőrzői. A C# programozási útmutatóban általános típusparaméterekről olvashat bővebben.

• Adjon általános típusparamétereket leíró névvel, kivéve, ha egy betűnév teljesen magától értetődő, és egy leíró név nem ad értéket.

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

• Fontolja meg aT név használatát az egybetűs típusparaméterrel rendelkező típusok típusparaméterének megadásához.

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

• Do előtag leíró típusú paraméterneveket a "T" betűvel.

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

• Fontolja meg, amely a paraméter nevében egy típusparaméterre vonatkozó korlátozásokat jelez. Például egy olyan paraméter, amely ISession-re van korlátozva, elnevezhető TSession-nek.

A CA1715 kódelemzési szabály használatával biztosítható, hogy a típusparaméterek neve megfelelően legyen elnevezve.

További elnevezési konvenciók

• Olyan példák, amelyek nem tartalmazzák a utasításokat ahasználatával, a névtér-kvalifikációkat alkalmazzák. Ha tudja, hogy a rendszer alapértelmezés szerint importál egy névteret egy projektben, nem kell teljes mértékben minősítenie a névtérben szereplő neveket. A minősített nevek pont (.) után törhetők fel, ha túl hosszúak egyetlen sorhoz, ahogy az alábbi példában is látható.

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

• Nem kell módosítania a Visual Studio designer eszközeivel létrehozott objektumok nevét, hogy azok megfeleljenek más irányelveknek.