Menulis komen php yang berkesan

Komen tidak boleh cuai kerana mereka ingin menjelaskan sebab-sebab kewujudan kod dan bukannya fungsi, seperti keserasian dengan antara muka lama atau sekatan pihak ketiga, jika tidak, orang yang membaca kod itu hanya boleh bergantung pada meneka. Bidang yang mesti dikomentari termasuk penghakiman bersyarat kompleks, logik pengendalian kesilapan khas, dan sekatan pintasan sementara. Cara yang lebih praktikal untuk menulis komen ialah memilih komen tunggal atau menyekat komen berdasarkan tempat kejadian. Gunakan komen blok dokumen untuk menerangkan parameter dan pulangan nilai pada permulaan fungsi, kelas, dan fail, dan simpan komen dikemas kini. Untuk logik yang kompleks, anda boleh menambah garis kepada yang sebelumnya untuk meringkaskan niat keseluruhan. Pada masa yang sama, jangan gunakan komen untuk menutup kod, tetapi gunakan alat kawalan versi.

Menulis komen PHP sebenarnya agak penting, tetapi ramai orang tidak melakukannya dengan betul. Komen bukan hanya ditulis hanya beberapa ayat. Kuncinya adalah untuk membantu orang lain (atau diri anda pada masa akan datang) memahami kod lebih cepat.

Mengapa tidak boleh komen tidak ceroboh?

Apabila banyak orang baru menulis komen, mereka suka menulis kandungan samar -samar seperti "fungsi ini melakukan sesuatu", yang sebenarnya bersamaan dengan tidak menulisnya. Komen yang baik harus menjelaskan mengapa kod ini wujud, bukan apa yang dilakukannya . Contohnya:

• Logik ini adalah untuk keserasian dengan versi lama antara muka
• Parameter tertentu perlu dikendalikan secara khusus kerana batasan perpustakaan pihak ketiga

Jika maklumat ini tidak ditulis, orang yang membaca kod itu hanya boleh meneka.

Di mana saya mesti menambah komen?

Sesetengah blok kod disyorkan untuk menambah komen walaupun mereka kelihatan sangat jelas, seperti:

• Penghakiman bersyarat kompleks, terutamanya ketika bersarang berbilang lapisan jika
• Logik pengendalian ralat khas
• Had yang perlu dilangkau sementara (contohnya, patch digunakan)

Sebagai contoh, jika anda mempunyai sekeping kod yang memproses penukaran format masa, hanya melihat kod mungkin tahu bahawa ia menukar format, tetapi tidak tahu mengapa anda mesti menggunakan strtotime() dan bukannya objek langsung DateTime. Pada masa ini, komen dapat menjimatkan banyak keraguan.

Bagaimana cara menulis komen lebih praktikal?

Terdapat dua kaedah anotasi yang biasa digunakan dalam php: satu-satunya komen talian // dan blok komen /* */ . Pemilihan yang disyorkan berdasarkan tempat kejadian:

• Gunakan penerangan ringkas //
• Fungsi, kelas, dan fail dikomentari dengan blok dokumen pada mulanya, seperti:

 /**
 * Proses logik log masuk pengguna, termasuk proses pengesahan pihak ketiga*
 * @param string $ nama pengguna username * @param string $ kata laluan * @return bool login berjaya */

Beberapa petua lain:

• Jangan gunakan komen untuk "mengelak" kepingan besar kod, gunakan alat kawalan versi sebaliknya
• Pastikan komen dikemas kini, jangan biarkan komen lama menyesatkan orang
• Sekiranya logiknya rumit, anda boleh menambah garis komen untuk meringkaskan niat keseluruhan

Titik Terakhir: Jangan takut menulis beberapa ayat lagi

Kadang -kadang anda akan berfikir, "Adakah kod ini tidak jelas?" Tetapi apabila anda kembali melihatnya dalam beberapa bulan, anda mungkin perlu memikirkannya untuk masa yang lama. Daripada menyesali selepas itu, lebih baik menghabiskan beberapa saat lagi menulisnya. Terutama untuk beberapa "titik pit" atau "amalan bukan standard", walaupun anda menulis satu atau dua lagi ayat, ia akan sangat membantu untuk generasi kemudian.

Pada asasnya, itu sahaja. Komen kelihatan kecil, tetapi ia benar -benar membazir perkara jika anda tidak dapat melakukannya dengan baik.

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