Aturan dan konvensi penamaan pengidentifikasi C#

2024-12-19

Pengidentifikasi adalah nama yang Anda tetapkan ke jenis (kelas, antarmuka, struktur, delegasi, atau enum), anggota, variabel, atau namespace.

Aturan penamaan

Pengidentifikasi yang valid harus mengikuti aturan ini. Pengkompilasi C# menghasilkan kesalahan untuk pengidentifikasi apa pun yang tidak mengikuti aturan ini:

Pengidentifikasi harus dimulai dengan huruf atau garis bawah (_).
Pengidentifikasi dapat berisi karakter huruf Unicode, karakter digit desimal, karakter penghubung Unicode, karakter gabungan Unicode, atau karakter pemformatan Unicode. Untuk informasi selengkapnya tentang kategori Unicode, lihat Database Kategori Unicode.

Anda dapat mendeklarasikan pengidentifikasi yang cocok dengan kata kunci C# dengan menggunakan awalan @ pada pengidentifikasi. @ bukan bagian dari nama pengidentifikasi. Misalnya, @if mendeklarasikan pengidentifikasi bernama if. Pengidentifikasi verbatim ini terutama digunakan untuk interoperabilitas dengan pengidentifikasi yang dinyatakan dalam bahasa lain.

Untuk definisi lengkap dari pengidentifikasi yang valid, lihat artikel Identifikasi dalam Spesifikasi Bahasa C#.

Penting

Spesifikasi bahasa C# hanya mengizinkan kategori huruf (Lu, Ll, Lt, Lm, atau Nl), digit (Nd), menyambungkan (Pc), menggabungkan (Mn atau Mc), dan pemformatan (Cf). Apa pun yang berada di luar secara otomatis diganti menggunakan _. Ini mungkin berdampak pada karakter Unicode tertentu.

Konvensi penamaan

Selain aturan, konvensi untuk nama pengidentifikasi digunakan di seluruh API .NET. Konvensi ini memberikan konsistensi untuk nama, tetapi pengkompilasi tidak memberlakukannya. Anda bebas menggunakan konvensi yang berbeda dalam proyek Anda.

Menurut konvensi, program C# menggunakan PascalCase untuk nama jenis, namespace, dan semua anggota publik. Selain itu, tim dotnet/docs menggunakan konvensi berikut, yang diadopsi dari gaya pengodatan tim .NET Runtime :

Nama antarmuka dimulai dengan huruf besar I.
Jenis atribut diakhir dengan kata Attribute.
Jenis enum menggunakan kata benda tunggal untuk bukan penanda, dan kata benda jamak untuk penanda.
Pengidentifikasi tidak boleh berisi dua karakter garis bawah berturut-turut (_). Nama-nama tersebut dicadangkan untuk pengidentifikasi yang dibuat oleh kompilator.
Gunakan nama yang bermakna dan deskriptif untuk variabel, metode, dan kelas.
Lebih suka kejelasan daripada singkatnya.
Gunakan PascalCase untuk nama kelas dan nama metode.
Gunakan camelCase untuk parameter metode dan variabel lokal.
Gunakan PascalCase untuk nama konstanta, baik bidang maupun konstanta lokal.
Bidang instans privat dimulai dengan garis bawah (_) dan teks yang tersisa adalah camelCased.
Bidang statis dimulai dengan s_. Konvensi ini bukan perilaku Visual Studio default, atau bagian dari panduan desain Framework, tetapi dapat dikonfigurasi dalam konfigurasi editor.
Hindari menggunakan singkatan atau akronim dalam nama, kecuali untuk singkatan yang dikenal dan diterima secara luas.
Gunakan namespace yang bermakna dan deskriptif yang mengikuti notasi nama domain terbalik.
Pilih nama rakitan yang mewakili tujuan utama rakitan.
Hindari menggunakan nama huruf tunggal, kecuali untuk penghitung perulangan sederhana. Selain itu, contoh sintaks yang menggambarkan sintaks konstruksi C# sering menggunakan nama huruf tunggal berikut yang cocok dengan konvensi yang digunakan dalam spesifikasi bahasa C#. Contoh sintaks adalah pengecualian untuk aturan.
- Gunakan S untuk struktur, C untuk kelas.
- Gunakan M untuk metode.
- Gunakan v untuk variabel, p untuk parameter.
- Gunakan r untuk parameter ref.

Kiat / Ujung / Petunjuk (depending on context)

Anda dapat menerapkan konvensi penamaan yang menyangkut kapitalisasi, awalan, akhiran, dan pemisah kata dengan menggunakan aturan penamaan gaya kode .

Dalam contoh berikut, panduan yang berkaitan dengan elemen yang ditandai public juga berlaku saat bekerja dengan elemen protected dan protected internal, yang semuanya dimaksudkan untuk terlihat oleh pemanggil eksternal.

Kasus Pascal

Gunakan penulisan huruf besar tipe Pascal ("PascalCasing") saat memberi nama jenis class, interface, struct, atau delegate.

public class DataService
{
}

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

public struct ValueCoordinate
{
}

public delegate void DelegateType(string message);

Saat menamai interface, gunakan penggunaan huruf besar-kecil Pascal dengan menambahkan awalan Ipada nama. Awalan ini dengan jelas menunjukkan kepada konsumen bahwa itu adalah interface.

public interface IWorkerQueue
{
}

Saat memberi nama public anggota jenis, seperti bidang, properti, peristiwa, gunakan casing pascal. Selain itu, gunakan casing pascal untuk semua metode dan fungsi lokal.

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

Saat menulis rekaman posisional, gunakan penulisan Pascal Casing untuk parameter karena mereka adalah properti publik dari rekaman tersebut.

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

Untuk informasi selengkapnya tentang rekaman posisional, lihat sintaks posisi untuk definisi properti.

Kasus Camel

Gunakan casing unta ("camelCasing") saat menamai bidang private atau internal dan awali dengan _. Gunakan CamelCase saat memberi nama variabel lokal, termasuk instans tipe delegasi.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Kiat / Ujung / Petunjuk (depending on context)

Saat mengedit kode C# yang mengikuti konvensi penamaan ini dalam IDE yang mendukung penyelesaian pernyataan, mengetik _ akan menampilkan semua anggota cakupan objek.

Saat bekerja dengan bidang static yang private atau internal, gunakan awalan s_, dan untuk utas statis gunakan t_.

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

Saat menulis parameter metode, gunakan casing unta.

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

Untuk informasi selengkapnya tentang konvensi penamaan C#, lihat gaya penulisan kode tim .NET Runtime di .

Pedoman penamaan parameter jenis

Panduan berikut berlaku untuk parameter tipe pada parameter jenis generik. Parameter jenis adalah tempat penampung untuk argumen dalam jenis generik atau metode generik. Anda dapat membaca selengkapnya tentang parameter jenis generik dalam panduan pemrograman C#.

Lakukan nama parameter jenis generik dengan nama deskriptif, kecuali nama huruf tunggal benar-benar jelas dan nama deskriptif tidak akan menambahkan nilai.

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

Pertimbangkan menggunakan T sebagai nama parameter jenis untuk jenis dengan satu parameter jenis huruf tunggal.

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

Gunakan awalan "T" untuk nama parameter jenis deskriptif.

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

Pertimbangkan yang menunjukkan pembatasan yang diterapkan pada parameter tipe dalam penamaan parameter. Misalnya, parameter yang dibatasi untuk ISession mungkin disebut TSession.

Aturan analisis kode CA1715 dapat digunakan untuk memastikan bahwa parameter jenis diberi nama dengan tepat.

Konvensi penamaan tambahan

Contoh yang tidak menyertakan menggunakan direktif, harus menggunakan kualifikasi namespace. Jika Anda tahu bahwa namespace diimpor secara default dalam proyek, Anda tidak perlu sepenuhnya memenuhi syarat nama dari namespace tersebut. Nama yang memenuhi syarat dapat dipecah setelah titik (.) jika terlalu panjang untuk satu baris, seperti yang ditunjukkan dalam contoh berikut.
```
var currentPerformanceCounterCategory = new System.Diagnostics.
    PerformanceCounterCategory();
```
Anda tidak perlu mengubah nama objek yang dibuat dengan menggunakan alat perancang Visual Studio agar sesuai dengan panduan lain.

Bagikan melalui