Mengulas PHP yang berkesan

Kunci untuk menulis komen PHP adalah jelas, berguna dan ringkas. 1. Komen harus menjelaskan niat di sebalik kod itu dan bukan hanya menggambarkan kod itu sendiri, seperti menjelaskan tujuan logik penghakiman bersyarat kompleks; 2. Tambahkan komen kepada senario utama seperti nilai sihir, keserasian kod lama, antara muka API, dan lain -lain untuk meningkatkan kebolehbacaan; 3. Elakkan kandungan kod pendua, simpan ringkas dan spesifik, dan gunakan format standard seperti phpDoc; 4. Komen harus dikemas kini secara serentak dengan kod untuk memastikan ketepatan. Komen yang baik harus difikirkan dari perspektif orang lain, mengurangkan kos pemahaman, dan menjadi kod pemahaman peranti navigasi.

Menulis komen PHP tidak sukar, tetapi sebenarnya agak khusus untuk menulisnya dengan jelas, berguna dan tanpa verbose. Ramai orang menulis komen sama ada terlalu mudah, seperti hanya menulis "Apa fungsi ini lakukan?" Atau ia terlalu rumit, dan mereka tidak dapat melihat perkara utama dengan jelas. Komen PHP yang benar -benar berkesan harus membuat orang melihat niat sekilas dan mengurangkan kos pemahaman.

Mengapa anda perlu menulis komen dengan jelas?

Anda mungkin berfikir bahawa kod itu boleh bercakap dengan sendirinya, tetapi sering, nama -nama yang berubah -ubah dan nama -nama fungsi tidak sepenuhnya menyatakan niat di sebalik logik. Terutama apabila logik perniagaan lebih rumit, tanpa komen seperti tanda jalan yang hilang, dan yang lain (walaupun diri anda) cenderung untuk tersesat apabila mereka kembali melihat kod tersebut.

Contohnya:

 jika ($ user-> peranan! == 'admin' && $ user-> status! == 'aktif') {
    kembali palsu;
}

Kod ini kelihatan mudah, tetapi jika anda menambah komen:

 // Operasi ini tidak dapat dilakukan oleh bukan pentadbir atau pengguna yang tidak diaktifkan

Maka makna keseluruhan penghakiman lebih jelas.

Oleh itu, peranan anotasi bukan sahaja untuk menunjukkan apa yang telah dilakukan, tetapi lebih penting lagi untuk menjelaskan mengapa ia dilakukan .

Di manakah yang paling layak mengulas?

Tidak setiap baris kod memerlukan komen, tetapi senario berikut disyorkan:

• Penghakiman bersyarat kompleks : Triple atau lebih jika/lain atau logik bersarang.
• Di mana nilai sihir berasal dari sumber yang tidak diketahui : Sebagai contoh, $type = 3 , jika 3 adalah kod status tertentu, lebih baik untuk menunjukkan makna.
• Aneh tetapi mesti dikekalkan Kod Lama : Kadang -kadang, untuk bersesuaian dengan sistem lama, anda perlu menulis beberapa kod yang tidak masuk akal, dan komen dapat membantu anda "menafikan liabiliti anda".
• Parameter Antara Muka API Keterangan : Terutama struktur nilai pulangan, ia sangat kritikal kepada pemanggil.

Contohnya:

 /**
 * Dapatkan maklumat pengguna*
 * @param int $ userid us id id
 * @return array mengandungi nama, e -mel, bidang peranan*/
fungsi getUserInfo ($ userId) {
    // ...
}

Anotasi dokumentari semacam ini juga boleh diminta secara automatik dalam IDE dan sangat praktikal.

Bagaimana untuk menulis komen supaya mereka tidak akan menjadi "tidak masuk akal"?

Terdapat juga cara untuk menulis komen, dan anda boleh merujuk kepada perkara berikut:

• Elakkan kandungan kod pendua : Jangan tulis komen seperti "tetapkan tajuk ke $ tajuk" kecuali ada sebab khas.
• Pastikan ia mudah tetapi spesifik : Jelaskan tujuannya, dan anda tidak perlu membuat ucapan yang panjang.
• Gunakan format standard : Anotasi berstruktur seperti PHPDOC lebih sesuai untuk kerja berpasukan.
• Kemas kini komen dalam masa : Jika kod diubah, komen mesti dikemas kini secara serentak, jika tidak, ia akan menjadi lebih buruk daripada tidak.

Beberapa petua:

• Selepas menulis perenggan logik, lihat kembali untuk melihat sama ada anda perlu menambah komen.
• Apabila melihat kod orang lain, perhatikan apa yang membuat anda terjebak, dan mereka adalah tempat yang perlu ditambah.
• Jika anda membaca sekeping kod dua kali sebelum anda memahami, maka komen yang anda tulis sekarang harus difahami oleh orang lain.

Pada dasarnya itu sahaja

Inti anotasi yang berkesan adalah untuk berfikir dari perspektif orang lain. Ia bukan pengulang untuk kod, tetapi navigator untuk membantu memahami. Jangan takut menulis komen, tetapi elakkan menulis secara rawak. Menulis dengan baik bukan sahaja dapat membantu orang lain, tetapi juga membantu anda dengan cepat mencari idea anda pada masa akan datang.

Atas ialah kandungan terperinci Mengulas PHP yang berkesan. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!