by 
Bayangkan Anda kembali membuka kode yang Anda tulis enam bulan lalu. Tanpa catatan, Anda akan bingung sendiri: “Kenapa baris ini saya tulis begini?” Di sinilah komentar berperan. Komentar adalah catatan di dalam kode yang diabaikan oleh mesin PHP, tetapi sangat berharga bagi manusia yang membacanya. Artikel ini membahas cara menulis komentar di PHP beserta praktik terbaiknya.
Tiga Gaya Komentar di PHP
<?php // Komentar satu baris gaya C++ # Komentar satu baris gaya shell /* Komentar banyak baris cocok untuk penjelasan panjang */ echo "Halo Dunia"; ?>
PHP mendukung tiga gaya: // dan # untuk satu baris, serta /* ... */ untuk beberapa baris sekaligus.
Contoh Kasus: Menonaktifkan Kode Sementara
Saat mencari sumber masalah (debugging), komentar sering dipakai untuk “mematikan” sebagian kode tanpa menghapusnya:
<?php $total = $harga * $jumlah; // $total = $total - $diskon; // sementara dinonaktifkan untuk uji coba echo $total; ?>
Contoh Kasus: Dokumentasi Fungsi (DocBlock)
Pada proyek nyata, fungsi biasanya diberi komentar khusus bergaya DocBlock yang bisa dibaca editor dan alat dokumentasi:
<?php
/**
* Menghitung harga setelah diskon.
*
* @param float $harga Harga awal
* @param float $persen Persentase diskon (0-100)
* @return float Harga akhir
*/
function hargaDiskon($harga, $persen) {
return $harga - ($harga * $persen / 100);
}
?>
Kesalahan Umum
- Komentar berlebihan: menjelaskan hal yang sudah jelas, misalnya
$i++; // tambah i, justru membuat kode berisik. - Komentar usang: kode diubah tetapi komentarnya lupa diperbarui, sehingga menyesatkan.
- Menyimpan kredensial di komentar: jangan pernah menulis kata sandi atau kunci API di komentar meski dinonaktifkan.
Tips Praktik Terbaik
Tulislah komentar yang menjelaskan mengapa, bukan apa. Kode sudah menunjukkan apa yang terjadi; komentar yang baik menjelaskan alasan atau konteks di baliknya.
Kesimpulan
Komentar adalah bentuk komunikasi kepada diri Anda di masa depan dan rekan tim. Gunakan // untuk catatan singkat, /* */ untuk penjelasan panjang, dan DocBlock untuk mendokumentasikan fungsi. Kode yang baik bukan yang penuh komentar, melainkan yang komentarnya tepat sasaran.
Referensi: untuk penjelasan lebih mendalam, kunjungi dokumentasi resmi PHP (php.net).
