Bagikan melalui

Aturan penamaan gaya kode

  • Artikel

Dalam file .editorconfig, Anda dapat menentukan konvensi penamaan untuk elemen kode bahasa pemrograman .NET—seperti kelas, properti, dan metode—dan bagaimana pengkompilasi atau IDE harus menerapkan konvensi tersebut. Misalnya, Anda dapat menentukan bahwa anggota publik yang tidak dikapitalisasi harus diperlakukan sebagai kesalahan kompilator, atau bahwa jika bidang privat tidak dimulai dengan _, peringatan build harus dikeluarkan.

Secara khusus, Anda dapat menentukan aturan penamaan, yang terdiri dari tiga bagian:

  • Grup simbol tempat aturan berlaku, misalnya, anggota publik atau bidang privat.
  • Gaya penamaan untuk dikaitkan dengan aturan, misalnya, bahwa nama harus dikapitalisasi atau dimulai dengan garis bawah.
  • Tingkat keparahan pesan saat elemen kode yang disertakan dalam grup simbol tidak mengikuti gaya penamaan.

Sintaks umum

Untuk menentukan salah satu entitas di atas—aturan penamaan, grup simbol, atau gaya penamaan—atur satu atau beberapa properti menggunakan sintaks berikut:

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

Semua pengaturan properti untuk tertentu kind dan entityName membentuk definisi entitas tertentu.

Setiap properti hanya boleh diatur sekali, tetapi beberapa pengaturan memungkinkan beberapa nilai yang dipisahkan koma.

Urutan properti tidak penting.

<nilai jenis>

<jenis> menentukan jenis entitas mana yang sedang didefinisikan—aturan penamaan, grup simbol, atau gaya penamaan—dan harus salah satu dari yang berikut ini:

Untuk mengatur properti untuk <Gunakan nilai jenis> Contoh
Aturan penamaan dotnet_naming_rule dotnet_naming_rule.types_should_be_pascal_case.severity = suggestion
Grup simbol dotnet_naming_symbols dotnet_naming_symbols.interface.applicable_kinds = interface
Gaya penamaan dotnet_naming_style dotnet_naming_style.pascal_case.capitalization = pascal_case

<entityName>

<entityName> adalah nama deskriptif yang Anda pilih yang mengaitkan beberapa pengaturan properti ke dalam satu definisi. Misalnya, properti berikut menghasilkan dua definisi grup simbol, interface dan types, yang masing-masing memiliki dua properti yang diatur di atasnya.

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

Setiap jenis entitas—aturan penamaan, grup simbol, atau gaya penamaan—memiliki properti yang didukung sendiri, seperti yang dijelaskan di bagian berikut.

Properti grup simbol

Anda dapat mengatur properti berikut untuk grup simbol, untuk membatasi simbol mana yang disertakan dalam grup. Untuk menentukan beberapa nilai untuk satu properti, pisahkan nilai dengan koma.

Properti Deskripsi Nilai yang diizinkan Wajib
applicable_kinds Jenis simbol dalam grup 1 * (gunakan nilai ini untuk menentukan semua simbol)
namespace
class
struct
interface
enum
property
method
field
event
delegate
parameter
type_parameter
local
local_function		 Ya
applicable_accessibilities Tingkat aksesibilitas simbol dalam grup * (gunakan nilai ini untuk menentukan semua tingkat aksesibilitas)
public
internal atau friend
private
protected
protected_internal atau protected_friend
private_protected
local (untuk simbol yang ditentukan dalam metode)		 Ya
required_modifiers Hanya cocokkan simbol dengan semua pengubah yang ditentukan 2 abstract atau must_inherit
async
const
readonly
static atau shared3		 Tidak

Catatan:

  1. Anggota Tuple saat ini tidak didukung di applicable_kinds.
  2. Grup simbol cocok dengan semua pengubah di required_modifiers properti . Jika Anda menghilangkan properti ini, tidak ada pengubah tertentu yang diperlukan untuk kecocokan. Ini berarti pengubah simbol tidak berpengaruh pada apakah aturan ini diterapkan atau tidak.
  3. Jika grup Anda memiliki static atau shared di required_modifiers properti , grup juga akan menyertakan const simbol karena secara static/Sharedimplisit . Namun, jika Anda tidak ingin static aturan penamaan diterapkan ke const simbol, Anda dapat membuat aturan penamaan baru dengan grup constsimbol . Aturan baru akan diutamakan sesuai dengan urutan aturan.
  4. class termasuk rekaman C#.

Properti gaya penamaan

Gaya penamaan menentukan konvensi yang ingin Anda tertibkan dengan aturan. Contohnya:

  • Kapitalkan dengan PascalCase
  • Dimulai dengan m_
  • Diakhir dengan _g
  • Pisahkan kata dengan __

Anda bisa mengatur properti berikut untuk gaya penamaan:

Properti Deskripsi Nilai yang diizinkan Wajib
capitalization Gaya kapitalisasi untuk kata-kata dalam simbol pascal_case
camel_case
first_word_upper
all_upper
all_lower		 Ya1
required_prefix Harus dimulai dengan karakter ini Tidak
required_suffix Harus diakhir dengan karakter ini Tidak
word_separator Kata-kata dalam simbol perlu dipisahkan dengan karakter ini Tidak

Catatan:

  1. Anda harus menentukan gaya kapitalisasi sebagai bagian dari gaya penamaan Anda, jika tidak, gaya penamaan Anda mungkin diabaikan.

Properti aturan penamaan

Semua properti aturan penamaan diperlukan agar aturan berlaku.

Properti Deskripsi
symbols Nama grup simbol yang ditentukan di tempat lain; aturan penamaan akan diterapkan ke simbol dalam grup ini
style Nama gaya penamaan yang harus dikaitkan dengan aturan ini; gaya didefinisikan di tempat lain
severity Mengatur tingkat keparahan untuk menerapkan aturan penamaan. Atur nilai terkait ke salah satu tingkat keparahan yang tersedia.1

Catatan:

  1. Spesifikasi tingkat keparahan dalam aturan penamaan hanya dihormati di dalam ID pengembangan, seperti Visual Studio. Pengaturan ini tidak dipahami oleh pengkompilasi C# atau VB, sehingga tidak dihormati selama build. Untuk menerapkan aturan gaya penamaan pada build, Anda harus mengatur tingkat keparahan dengan menggunakan konfigurasi tingkat keparahan aturan kode. Untuk informasi lebih lanjut, lihat masalah GitHub ini.

Urutan aturan

Urutan di mana aturan penamaan didefinisikan dalam file EditorConfig tidak masalah. Aturan penamaan secara otomatis diurutkan sesuai dengan definisi aturan itu sendiri. Aturan yang lebih spesifik mengenai aksesibilitas, pengubah, dan simbol lebih diutamakan daripada aturan yang kurang spesifik. Jika ada tumpang tindih antara aturan atau jika pengurutan aturan menyebabkan masalah, Anda dapat memecah persimpangan kedua aturan menjadi aturan baru yang lebih diutamakan daripada aturan yang lebih luas dari mana aturan tersebut diturunkan. Misalnya, lihat Contoh: Strategi penamaan tumpang tindih dan Contoh: const pengubah menyertakan static dan readonly.

Ekstensi EditorConfig Language Service dapat menganalisis file EditorConfig dan kasus laporan di mana urutan aturan dalam file berbeda dengan apa yang akan digunakan pengkompilasi pada waktu proses.

Catatan

Jika Anda menggunakan versi Visual Studio yang lebih lama dari Visual Studio 2019, aturan penamaan harus diurutkan dari yang paling spesifik hingga paling tidak spesifik dalam file EditorConfig. Aturan pertama yang ditemui yang dapat diterapkan adalah satu-satunya aturan yang diterapkan. Namun, jika ada beberapa properti aturan dengan nama yang sama, properti yang terakhir ditemukan dengan nama tersebut lebih diutamakan. Untuk informasi selengkapnya, lihat Hierarki dan prioritas file.

Contoh: Strategi penamaan yang tumpang tindih

Pertimbangkan dua aturan penamaan berikut:

  1. Metode publik adalah PascalCase.
  2. Metode asinkron diakhapi dengan "Async".

Untuk public async metode, tidak jelas aturan mana yang diutamakan. Anda dapat membuat aturan baru untuk public async metode dan menentukan penamaan dengan tepat.

Contoh: const pengubah mencakup static dan readonly

Pertimbangkan dua aturan penamaan berikut:

  1. Bidang konstanta adalah PascalCase.
  2. Bidang non-publik static s_camelCase.

Aturan 2 lebih spesifik dan diutamakan, sehingga semua bidang konstanta non-publik s_camelCase. Untuk mengatasi masalah ini, Anda dapat menentukan aturan persimpangan: bidang konstanta non-publik adalah PascalCase.

Gaya penamaan default

Jika Anda tidak menentukan aturan penamaan kustom apa pun, gaya default berikut digunakan:

  • Untuk kelas, struktur, enumerasi, properti, metode, dan peristiwa dengan aksesibilitas apa pun, gaya penamaan default adalah kasus Pascal.

  • Untuk antarmuka dengan aksesibilitas apa pun, gaya penamaan default adalah kasus Pascal dengan awalan I yang diperlukan.

ID Aturan Kode: IDE1006 (Naming rule violation)

Semua opsi penamaan memiliki ID IDE1006 aturan dan judul Naming rule violation. Anda dapat mengonfigurasi tingkat keparahan pelanggaran penamaan secara global dalam file EditorConfig dengan sintaks berikut:

dotnet_diagnostic.IDE1006.severity = <severity value>

Nilai tingkat keparahan harus warning atau error diberlakukan pada build. Untuk semua kemungkinan nilai tingkat keparahan, lihat tingkat keparahan.

Contoh: Kapitalisasi anggota publik

File .editorconfig berikut berisi konvensi penamaan yang menentukan bahwa properti publik, metode, bidang, peristiwa, dan delegasi yang ditandai readonly harus dikapitalisasi. Konvensi penamaan ini menentukan beberapa jenis simbol untuk menerapkan aturan, menggunakan koma untuk memisahkan nilai.

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

Contoh: Bidang instans privat dengan garis bawah

Cuplikan file .editorconfig ini memberlakukan bahwa bidang instans privat harus dimulai dengan _; jika konvensi tersebut tidak diikuti, IDE akan memperlakukannya sebagai kesalahan kompilator. Bidang statis privat diabaikan.

Karena Anda hanya dapat menentukan grup simbol berdasarkan pengidentifikasi yang dimilikinya (misalnya, static atau readonly), dan bukan oleh pengidentifikasi yang tidak dimilikinya (misalnya, bidang instans karena tidak memiliki static), Anda perlu menentukan dua aturan penamaan:

  1. Semua bidang privat— static atau tidak—harus memiliki underscored gaya penamaan yang diterapkan sebagai pengkompilasi error.
  2. Bidang privat dengan harus memiliki underscored gaya penamaan yang diterapkan padanya dengan tingkat nonekeparahan ; dengan static kata lain, abaikan kasus ini.
[*.{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

Contoh ini juga menunjukkan bahwa definisi entitas dapat digunakan kembali. Gaya underscored penamaan digunakan oleh private_fields_underscored aturan penamaan dan private_static_fields_none .

Baca juga