Hanya ada dua hal yang sulit dalam Ilmu Komputer: pembatalan cache
dan menyebutkan berbagai hal.
- Phil Karlton
Kami, pengembang, menghabiskan lebih banyak waktu membaca kode daripada menulisnya. Penting agar kode dapat dibaca dan jelas tentang maksudnya.
Di bawah ini adalah beberapa saran berdasarkan pengalaman saya menyebutkan hal-hal.
Berarti
Nama, baik itu variabel, properti, kelas, atau antarmuka, harus mencerminkan tujuan mengapa itu diperkenalkan dan bagaimana digunakan.
Gunakan nama yang akurat
Jika seseorang tidak bisa mendapatkan ide tentang penggunaan dan tujuan tanpa komentar tambahan, namanya tidak cukup baik. Jika penggunaan langsung atau ide tujuan berdasarkan penamaan salah maka penamaan tidak dapat diterima.
Penamaan terburuk yang mungkin adalah ketika nama metode terletak pada orang yang membacanya.
Hindari nama yang tidak berarti
Ini adalah nama-nama seperti $i , $j , $k dll. Meskipun ini OK untuk digunakan dalam siklus, dalam kasus lain mereka terbuang pembacaan.
Sumber umum nama-nama tersebut adalah sains klasik di mana sebagian besar rumus menggunakan variabel satu huruf sehingga lebih cepat untuk menulis. Sebagai konsekuensinya, Anda tidak dapat memahami formula ini tanpa paragraf pengantar yang menjelaskan penamaan. Seringkali paragraf ini sulit ditemukan.
Karena pendidikan sains komputer mencakup sejumlah besar disiplin sains klasik, siswa terbiasa dengan penamaan tersebut dan membawanya ke pemrograman.
Penamaan kelas, antarmuka, properti, dan metode
Nama kelas harus satu atau beberapa kata benda. Seharusnya tidak ada kata kerja. Coba hindari "data", "manajer", "info", "prosesor", "handler", "pembuat", "util" dll. karena ini biasanya merupakan indikator penamaan yang tidak jelas.
Antarmuka biasanya berupa kata benda atau kata sifat. Beberapa tim, termasuk PHP-FIG , memilih untuk memposting antarmuka dengan Interface . Beberapa melakukannya dengan awalan I dan beberapa menggunakan awalan atau postfix. Saya menemukan semua ini dapat diterima jika Anda konsisten.
Properti harus dinamai dengan kata benda atau kata sifat. Untuk boolean, gunakan frasa afirmatif yang diawali dengan "Is", "Can", atau "Has" jika perlu.
Nama metode harus mengandung satu atau lebih kata kerja karena itu adalah tindakan. Pilih kata kerja yang menjelaskan apa yang dilakukan metode, bukan bagaimana melakukannya.
Meskipun tidak sepenuhnya diperlukan, adalah ide yang bagus untuk mengakhiri nama kelas turunan dengan nama kelas dasar:
class Exception {} class InvalidArgumentException extends Exception {}
Konsistensi
Gunakan satu nama untuk satu konsep. Bersikaplah konsisten.
Contoh yang baik adalah menggunakan begin / end mana-mana alih-alih mencampurnya dengan start / finish .
Ikuti konvensi gaya kode
Saat mengembangkan proyek, tim harus menyetujui gaya kode dan konvensi penamaan yang mereka gunakan dan ikuti ini. Jika bagian dari konvensi tidak diterima oleh beberapa anggota tim maka harus ditinjau, diubah dan aturan baru harus ditetapkan.
Untuk PHP, konvensi yang paling umum saat ini adalah PSR-2 dan kebanyakan konvensi proyek internal didasarkan padanya.
Verbositas
Hindari menggunakan kembali nama
Menggunakan nama yang sama untuk banyak konsep harus dihindari jika memungkinkan karena membawa dua masalah:
- Saat membaca, Anda harus mengingat konteks. Biasanya itu berarti mendapatkan deklarasi namespace atau paket secara konstan.
- Mencari nama-nama seperti itu menyakitkan.
Hindari kontraksi
Jangan gunakan kontraksi. Contoh umum adalah:
function cntBigWrds($data, $length) { $i = 0; foreach ($data as $iter) { if (mb_strlen($iter) > $length) { $i++; } } return $i; } $data = ['I', 'am', 'word']; echo cntBigWrds($data, 3);
Kode di atas ketika dinamai dengan benar menjadi:
function countWordsLongerThan(array $words, int $minimumLength) { $count = 0; foreach ($words as $word) { if (mb_strlen($word) > $minimumLength) { $count++; } } return $count; } $words = ['I', 'am', 'word']; echo countWordsLongerThan($words, 3);
Perhatikan bahwa nama-nama penjelasan pendek tanpa kontraksi lebih baik daripada nama-nama penjelasan yang panjang sehingga tidak menggunakan verbositas untuk berakhir ekstrem dengan nama-nama seperti processTextReplacingMoreThanASingleSpaceWithASingleSpace() .
Jika namanya terlalu panjang itu berarti dapat diucapkan ulang untuk membuatnya lebih pendek atau hal yang Anda beri nama terlalu banyak dan harus di refactored menjadi beberapa hal.
Hindari akronim
Hindari akronim dan singkatan kecuali yang umum dikenal seperti HTML. Elon Musk mengirim email berjudul "Acronyms Seriously Suck" ke semua karyawan SpaceX pada Mei 2010:
Ada kecenderungan merayap untuk menggunakan akronim yang dibuat di SpaceX. Penggunaan akronim yang berlebihan secara berlebihan merupakan penghambat yang signifikan terhadap komunikasi dan menjaga komunikasi yang baik saat kita tumbuh adalah sangat penting. Secara individual, beberapa akronim di sana-sini mungkin tidak begitu buruk, tetapi jika seribu orang mengada-ada, seiring waktu hasilnya akan menjadi daftar istilah besar yang harus kita keluarkan kepada karyawan baru. Tidak ada yang benar-benar dapat mengingat semua akronim ini dan orang tidak ingin terlihat bodoh dalam rapat, jadi mereka hanya duduk di sana dengan kebodohan. Ini sangat sulit pada karyawan baru.
Itu perlu segera dihentikan atau saya akan mengambil tindakan drastis - saya telah memberikan peringatan yang cukup selama bertahun-tahun. Kecuali jika akronim disetujui oleh saya, itu tidak boleh masuk ke daftar istilah SpaceX. Jika ada akronim yang sudah ada yang tidak bisa dibenarkan, itu harus dihilangkan, seperti yang saya minta di masa lalu.
Misalnya, seharusnya tidak ada sebutan "HTS" [dudukan uji horizontal] atau "VTS" [dudukan uji vertikal] untuk dudukan uji. Itu sangat bodoh, karena mengandung kata-kata yang tidak perlu. "Dudukan" di lokasi pengujian kami jelas merupakan dudukan uji. VTS-3 adalah empat suku kata dibandingkan dengan "Tripod", yang dua, sehingga versi akronim berdarah sebenarnya lebih lama untuk mengatakan daripada namanya!
Tes kunci untuk akronim adalah menanyakan apakah itu membantu atau melukai komunikasi. Singkatan yang sebagian besar insinyur di luar SpaceX sudah tahu, seperti GUI, boleh digunakan. Tidak apa-apa untuk membuat beberapa akronim / kontraksi setiap sekarang dan lagi, dengan asumsi saya telah menyetujuinya, misalnya MVac dan M9 alih-alih Merlin 1C-Vacuum atau Merlin 1C-Level Air Laut, tetapi itu harus dijaga agar tetap minimum.
Saya setuju dengannya.
Keterbacaan
Kode harus dapat dibaca semudah prosa. Pilih kata-kata yang akan Anda pilih untuk menulis artikel atau buku. Misalnya, properti bernama TotalAmount lebih mudah dibaca dalam bahasa Inggris daripada AmountTotal .
Menyembunyikan detail implementasi
Itu lebih tentang desain berorientasi objek tetapi itu mempengaruhi keterbacaan banyak jika detail implementasi diekspos. Cobalah untuk tidak mengekspos metode bernama seperti:
initializeinitcreatebuild
Bahasa domain
Kode harus menggunakan nama yang sama seperti yang digunakan dalam model bisnis atau domain otomatis.
Misalnya, jika bisnis perjalanan menggunakan "tempat" sebagai nama umum untuk kafe, hotel, dan tempat wisata, adalah ide yang buruk untuk menggunakan "tempat" dalam kode karena Anda dan pengguna Anda akan berbicara dua bahasa berbeda sehingga lebih rumit dari yang seharusnya.
Bahasa seperti itu sering disebut "The Ubiquitous Language". Anda dapat belajar lebih banyak dari buku mini " Domain Driven Design Quickly " oleh InfoQ.
Bahasa inggris
Mayoritas bahasa pemrograman menggunakan bahasa Inggris untuk konstruksi bawaan dan merupakan praktik yang baik untuk menyebutkan berbagai hal dalam bahasa Inggris juga. Sangat penting bagi pengembang untuk belajar bahasa Inggris setidaknya pada tingkat dasar dan, yang lebih penting, untuk memiliki kosa kata yang baik yang dapat digunakan seseorang untuk menemukan nama yang baik.
Beberapa alat yang berguna:
Referensi