Panduan penamaan metode ringkas yang bermakna

Baru-baru ini saya mulai merilis proyek open source, sementara saya adalah satu-satunya pengguna perpustakaan saya tidak peduli dengan nama-nama itu, tetapi saya tahu saya ingin menetapkan nama pintar untuk setiap metode agar lebih mudah dipelajari, tetapi saya juga perlu menggunakan nama ringkas sehingga mudah untuk ditulis.

Saya sedang memikirkan beberapa pedoman tentang penamaan, saya menyadari banyak pedoman yang hanya peduli casing huruf atau beberapa catatan sederhana. Di sini, saya mencari pedoman untuk penamaan yang bermakna namun ringkas.

Misalnya, ini bisa menjadi bagian dari pedoman yang saya cari:

• Gunakan Tambah saat item yang ada akan ditambahkan ke target, Gunakan Buat saat item baru sedang dibuat dan ditambahkan ke target.
• Gunakan Hapus saat item yang ada akan dihapus dari target, Gunakan hapus ketika item akan dihapus secara permanen.
• Pasangkan metode AddXXX dengan RemoveXXX dan Pair metode CreateXXX dengan metode DeleteXXX, tetapi jangan mencampurnya.

Seperti yang ditunjukkan oleh contoh di atas, saya ingin menemukan beberapa materi daring yang membantu saya dengan metode penamaan dan item lain yang sesuai dengan tata bahasa Inggris dan makna kata.

Panduan di atas mungkin intuitif untuk penutur bahasa Inggris asli, tetapi bagi saya bahwa bahasa Inggris adalah bahasa kedua saya, saya perlu diberitahu tentang hal-hal seperti ini.

Penamaan. Salah satu hal tersulit tentang pengembangan perangkat lunak :)

Ketika saya memberi nama sesuatu, inilah prioritas saya:

• Ikuti idiom bahasa saya. Ruby suka garis bawah. Javascript suka case unta. Bahasa apa pun yang Anda gunakan adalah kebiasaan untuk diikuti.
• Mengungkapkan maksud API. Itu bukan "send_http_data" itu "post_twitter_status"
• Hindari membocorkan detail implementasi. Katakan, awalan variabel dengan tipe.
• Tidak menggunakan lebih banyak karakter dari yang diperlukan tanpa melanggar pedoman sebelumnya.

Jelas ini adalah pendekatan yang agak sederhana. Penamaan bernuansa.

Untuk penelitian lebih lanjut, saya akan merekomendasikan membaca The Art of Readable Code , karena memberikan beberapa saran yang sangat bagus dan ringkas tentang penamaan metode. Untuk penelitian lebih lanjut, saya sangat merekomendasikan Kode Bersih Bob Martin

Godaan untuk mengkodifikasi gaya atau konvensi untuk penamaan dalam beberapa kasus dapat menyebabkan kebiasaan yang dianggap praktik buruk saat ini, seperti menggunakan Notasi Hongaria misalnya. Jawaban sederhananya adalah melupakan konvensi penamaan dan gaya seolah-olah itu adalah hal yang terpisah untuk ditentukan secara terpisah, dan alih-alih fokus pada penamaan segala sesuatu di sistem Anda berdasarkan apa yang sebenarnya diwakilinya. Nama metode akan cenderung singkat jika Anda membatasi fungsionalitas setiap metode sehingga hanya melakukan satu hal secara tidak resmi, dan jika nama metode Anda benar-benar menggambarkan satu hal yang seharusnya dilakukan oleh metode tersebut.

Variabel, bidang, nama kelas dan file adalah sesuatu yang lain. Saya menyarankan bahwa jika nama variabel menjadi terlalu panjang, maka Anda mencoba untuk mendeskripsikan item-item ini terlalu detail, atau mereka mewakili sesuatu yang kompleks yang harus dipecah menjadi bagian-bagian yang lebih kecil, atau mungkin dijelaskan secara lebih abstrak. cara.

Pada akhir hari, Anda ingin menghindari kode jelek dengan nama-nama yang menempati seluruh baris, atau yang sangat fasih untuk merampok nilai mereka.

Bagi saya, menemukan nama baik untuk sesuatu selalu kembali ke memikirkannya sebagai objek yang harus membenarkan keberadaannya. Bertanya pada diri sendiri:

• Apa yang dilakukan oleh kelas / metode / variabel, yaitu apa tujuan yang lebih luas dan untuk apa?
• Apa yang spesifik tentang tujuannya yang perlu dikomunikasikan, yaitu apa bagian penting yang perlu dimiliki oleh nama itu di dalamnya?

Kebanyakan pengembang akan setuju bahwa keterbacaan selalu sangat penting dalam hal penamaan. Jangan hanya menulis kode sehingga Anda tahu apa yang Anda maksud saat Anda menulisnya, tulislah sehingga seseorang yang melihat kode untuk pertama kalinya di beberapa titik di masa depan tahu apa yang Anda maksud tanpa harus terlalu banyak berpikir. Anda akan menulis kode hanya sekali, tetapi selama masa pakai kode kemungkinan besar harus diedit berkali-kali dan membaca lebih banyak lagi.

Kode harus mendokumentasikan diri sendiri, yaitu, penamaan Anda harus memperjelas apa yang dilakukan sesuatu. Jika Anda perlu menjelaskan apa yang dilakukan oleh baris kode dalam komentar, dan mengubah nama hal-hal yang tidak cukup meningkatkannya, Anda harus secara serius mempertimbangkan refactoring baris itu menjadi metode baru dengan nama deskriptif yang tepat, sehingga membaca metode asli, yang metode panggilan baru menjelaskan apa yang terjadi. Jangan takut memiliki nama panjang; tentu saja Anda tidak boleh menulis novel di kelas / metode / nama variabel, tetapi saya lebih suka memiliki nama yang terlalu panjang dan deskriptif daripada terlalu pendek dan saya perlu mencari tahu apa fungsinya dengan mencari di bawah tenda. Kecuali untuk beberapa pengecualian yang jelas seperti koordinat x / y dan akronim yang umum digunakan, hindari nama dan singkatan karakter tunggal. Memanggil sesuatu "bkBtn" bukannya "backButton"

Sebisa mungkin bahasa Anda, buat kode Anda dibaca seperti kalimat bahasa Inggris. Objek menggunakan kata benda, metode menggunakan kata kerja. Metode Boolean biasanya dimulai dengan "is", tetapi ada banyak opsi lain yang menyampaikan makna lebih baik, tergantung pada use case, seperti "can", "should", atau "does". Tentu saja, tidak semua bahasa bisa sebagus Smalltalk dalam hal ini, tetapi beberapa simbol umumnya dipahami sebagai bagian dari kalimat. Dua konvensi Smalltalk yang secara pribadi ingin saya bahas dalam bahasa lain sebanyak mungkin adalah awalan nama parameter loop dengan "masing-masing", dan awalan parameter metode dengan artikel "a" (atau "an", atau "beberapa" untuk koleksi) . Ini mungkin bukan standar umum di Jawa, dan siapa pun boleh mengabaikan bit ini, tetapi saya menemukan bahwa ini sangat meningkatkan keterbacaan kode. Misalnya (misalnya di Jawa):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Ini harus dapat dibaca oleh orang-orang yang hanya memiliki sedikit pengetahuan tentang Jawa sebagai sesuatu seperti ini:

Untuk menentukan apakah Anda harus mempertimbangkan untuk menyingkat daftar beberapa nama (yang merupakan string), beralihlah ke beberapa nama, dan untuk setiap nama, tentukan apakah itu terlalu panjang; jika demikian, kembali true; jika tidak ada yang terlalu panjang, kembalilah false.

Bandingkan kode di atas hanya dengan menamai argumen stringsdan variabel loop string, terutama dalam metode yang lebih kompleks. Anda harus melihat lebih dekat untuk melihat perbedaannya daripada penggunaannya yang jelas dari pandangan sekilas pada namanya.

Menemukan nama yang bagus selalu merupakan kompromi di antara lebih banyak faktor. Anda tidak akan pernah puas sepenuhnya.

Yang mengatakan, bahkan jika bahasa asli Anda tidak seperti itu, pertimbangkan bahwa bahasa Inggris adalah bahasa yang token bahasa pemrogramannya dibentuk. Menggunakan sintaks seperti bahasa Inggris membuat pembacaan kode lebih "lancar" karena tidak ada "aturan pembacaan yang rusak" setiap kali kata kunci ditemukan.

Secara umum, pertimbangkan hal-hal seperti object.method(parameters)mencocokkan skema seperti subject.verb(complements).

Poin kuncinya, jika Anda harus mendukung pemrograman generik, adalah memilih satu set "kata kerja" yang baik dan konsisten (terutama yang perlu digunakan dalam algoritma generik).

Tentang kata benda, kelas harus diberi nama untuk apa yang mereka are(dalam hal konsep), sementara objek untuk apa mereka are for.

Yang mengatakan, antara list.add(component)dan component.add_to(list)lebih suka yang pertama. Secara umum kata kerja "transitif aktif" lebih baik mewakili tindakan sehubungan dengan rekan pasif atau refleksif mereka. Kecuali jika desain membatasi Anda.

Jangan khawatir tentang panjang nama metode. Pastikan nama metode mencerminkan dengan jelas apa yang mereka lakukan. Ini sangat penting untuk hal lain. Jika Anda merasa nama metode terlalu panjang, gunakan tesaurus untuk menemukan kata yang lebih pendek yang berarti hal yang sama. Misalnya gunakan Findsebagai ganti Retrieve.

Yang juga sama pentingnya adalah nama yang Anda pilih untuk kelas Anda. Ini memberikan banyak konteks ketika melihat nama metode. Tanda tangan metode seperti:

public User Find(int userId);

lebih mudah dipahami daripada:

public Person Find(int personId);

karena konteks yang diperoleh dari nama kelas Usermemberi tahu programmer bahwa Find()untuk menemukan tipe orang tertentu, pengguna sistem Anda. Versi yang menggunakan Personkelas tidak memberi Anda konteks tentang mengapa Anda bahkan perlu menggunakan metode ini.

Lihatlah bagaimana orang lain di platform Anda melakukannya - beberapa pemain besar bahkan mungkin memiliki gaya kode dan pedoman penamaan.

Beberapa platform lebih suka nama pendek (misalnya, dalam API Win32 C _tcsstradalah fungsi untuk menemukan string dalam string - bukankah itu jelas?), Yang lain menggunakan keterbacaan untuk mendukung singkatnya (dalam kerangka kerja Cocoa Apple untuk Objective-C) , metode untuk mengganti substring dalam string dengan string lain dan mengembalikan hasilnya sebagai salinan dipanggilstringByReplacingOccurrencesOfString: withString: ). Saya menemukan yang terakhir jauh lebih mudah dimengerti, dan hanya cukup sulit untuk menulis (terutama dengan penyelesaian kode).

Karena Anda membaca kode lebih sering daripada menulisnya (berlaku ganda untuk pustaka sumber terbuka), dan membaca lebih sulit daripada menulis, optimalkan untuk membaca. Optimalkan untuk brevity hanya bertahan lama, dan ambil hanya sebanyak mungkin tanpa mengurangi kejelasan.

1. Asumsikan bahasa Inggris, kecuali jika setiap pengembang yang pernah bekerja pada kode ini akan berbicara bahasa non-Inggris yang sama.

2. Pelajari konvensi dan gaya penamaan yang diterima secara umum. Prinsip panduan Anda harus jelas. Gaya berbeda menurut bahasa pemrograman.

3. Tidak ada yang dapat Anda lakukan dengan penamaan yang akan membuatnya lebih mudah untuk memahami hubungan antara berbagai objek dalam kode Anda. Untuk itu, Anda masih membutuhkan komentar dan dokumentasi yang ditulis dengan baik.

1. Gunakan awalan. Jika sekelompok metode digunakan untuk melakukan sesuatu yang serupa atau dapat dengan cara tertentu dikelompokkan bersama, letakkan awalan umum di depan nama mereka untuk menunjukkan kesamaan metode tersebut.
2. Jangan gunakan singkatan yang tidak jelas jika Anda ingin orang lain memahami nama secara instan (penting dalam penamaan API)