Amalan untuk Konvensyen Penamaan Deskriptif dalam PHP: Panduan Menulis Kod Bersih dan Boleh Dibaca

Konvensyen penamaan deskriptif membantu menjadikan kod anda lebih mudah dibaca, boleh diselenggara dan mendokumentasikan diri. Dengan menggunakan nama yang menyampaikan tujuan pembolehubah, fungsi dan kelas dengan jelas, anda membantu diri anda sendiri dan orang lain memahami kod anda tanpa memerlukan ulasan atau penjelasan tambahan.

Begini cara anda boleh mengguna pakai konvensyen penamaan deskriptif dengan garis panduan praktikal dan contoh dalam PHP:

1. Gunakan Kata Nama untuk Nama Kelas

• Nama kelas hendaklah mewakili entiti yang mereka uruskan. Nama kelas deskriptif menjelaskan peranan kelas dalam sistem anda.
• Gunakan PascalCase untuk nama kelas.
• Gunakan nama yang mencerminkan objek atau tanggungjawab kelas.

Contoh:

UserAccountManager: Kelas yang bertanggungjawab untuk mengurus akaun pengguna.
InvoiceGenerator: Kelas yang mengendalikan penjanaan invois.
ShoppingCart: Kelas yang mewakili sistem troli beli-belah.

2. Gunakan Kata Kerja untuk Nama Fungsi dan Kaedah

• Kaedah melakukan tindakan, jadi ia harus dinamakan dengan kata kerja atau frasa kata kerja yang menerangkan perkara yang mereka lakukan.
• Gunakan camelCase untuk nama kaedah dan fungsi.
• Awalan dengan kata kerja seperti dapatkan, tetapkan, cipta, kemas kini, padam, ialah, telah, dll., untuk kejelasan.

Contoh:

createUser(): Menyatakan dengan jelas bahawa fungsi ini mencipta pengguna.
calculateTotalAmount(): Menghuraikan tindakan mengira jumlah amaun.
isUserLoggedIn(): Kaedah yang menyemak sama ada pengguna telah log masuk.

3. Menjadi Spesifik dengan Nama Pembolehubah

• Pembolehubah hendaklah menunjukkan perkara yang disimpan atau diwakilinya.
• Elakkan nama pendek atau samar-samar seperti $x, $val, $data.
• Gunakan camelCase untuk nama berubah-ubah.
• Fikirkan tentang skop dan niat pembolehubah.

Contoh:

$totalOrderAmount: Menyimpan jumlah keseluruhan untuk pesanan.
$userEmailAddress: Jelas menunjukkan ia memegang alamat e-mel pengguna.
$invoiceItems: Mewakili item dalam invois, bukan hanya $items generik.

4. Elakkan Nama Terlalu Umum

• Elakkan nama seperti $data, $info, $result melainkan ia sangat bermakna dalam konteks itu.
• Sediakan konteks khusus jika sesuai, seperti $userData, $productInfo atau $searchResult.

5. Pembolehubah Boolean Harus Bertanya Soalan

• Jika pembolehubah ialah boolean, namanya harus mencerminkan soalan benar/salah.
• Penggunaan ialah, telah, sepatutnya, boleh sebagai awalan untuk menjelaskan ia adalah boolean.

Contoh:

$isActive: Jelas mencadangkan ia adalah boolean untuk menyemak sama ada sesuatu itu aktif.
$hasAccess: Menyemak sama ada pengguna mempunyai akses kepada sumber.
$canEdit: Menunjukkan sama ada pengguna semasa boleh mengedit item.

6. Pemalar Harus Deskriptif dan Spesifik

• Pemalar harus mencerminkan nilai tidak berubah dan ditulis dalam UPPERCASE_SNAKE_CASE.
• Elakkan nama generik seperti DEFAULT_VALUE dan lebih suka nama yang lebih deskriptif.

Contoh:

MAX_LOGIN_ATTEMPTS: Menghuraikan dengan jelas percubaan log masuk maksimum yang dibenarkan.
DEFAULT_CURRENCY_CODE: Menerangkan kod mata wang yang digunakan dalam urus niaga.
ERROR_CODE_INVALID_EMAIL: Kod ralat deskriptif yang berkaitan dengan kegagalan pengesahan e-mel.

7. Penamaan Koleksi

• Jika pembolehubah mewakili koleksi (mis., tatasusunan item), jelaskannya dengan menggunakan kata nama majmuk atau menambah senarai perkataan.

Contoh:

$userList: Koleksi pengguna.
$products: Koleksi objek produk.
$orderItems: Satu susunan item dalam satu pesanan.

Contoh Praktikal

class ShoppingCart {
    private $cartItems = [];
    private $totalCartValue = 0;

    public function addItemToCart($productId, $quantity) {
        $itemPrice = $this->getProductPriceById($productId);
        $this->cartItems[] = [
            'productId' => $productId,
            'quantity' => $quantity,
            'price' => $itemPrice

Atas ialah kandungan terperinci Amalan untuk Konvensyen Penamaan Deskriptif dalam PHP: Panduan Menulis Kod Bersih dan Boleh Dibaca. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!