Fondasi PHP

BAB 4: Komentar

Cara menulis komentar PHP yang tidak merusak program, plus 3 pesan parse error akibat penanda komentar yang salah tempat.

Komentar menjelaskan alasan, bukan mengulang kode

Komentar adalah bagian berkas PHP yang tidak dijalankan dan tidak dikirim ke browser. Parser membuangnya sebelum program berjalan, sehingga satu berkas boleh memuat penjelasan panjang tanpa mengubah satu pun hasil keluaran.

Dokumentasi PHP menyebut 3 gaya komentar: // dan # untuk satu baris, serta /* */ untuk blok. Ketiganya berhenti pada penanda yang berbeda, dan perbedaan itulah yang menentukan apakah sebuah catatan aman dipakai atau justru merusak berkas.

Setelah bab ini selesai, kamu bisa memilih gaya komentar yang sesuai dengan isi catatannya, membaca pesan Unterminated comment dan unexpected token, serta membedakan komentar biasa dari docblock yang bisa dibaca program lain.

3 gaya komentar, dan yang bukan komentar

Simpan berkas tiga-gaya.php:

PHPPHP
<?php

// Komentar satu baris dengan garis miring ganda
# Komentar satu baris dengan tanda pagar
/* Komentar blok
   yang memakan beberapa baris */

$alamat = "http://contoh.test/beranda"; // garis miring ganda di dalam string

echo "Halo, komentar tidak ikut tercetak", PHP_EOL;
echo $alamat, PHP_EOL;
echo "Total: /* ini tercetak apa adanya */", PHP_EOL;
echo "Harga #1", PHP_EOL;

$total = 25000 * 3; // komentar boleh menempel di ujung baris kode
echo "Total: ", $total, PHP_EOL;

Jalankan berkas itu dengan php tiga-gaya.php, hitung ukuran kedua berkas dengan wc -c, lalu hitung byte keluaran masing-masing:

CodeTEXT
Halo, komentar tidak ikut tercetak
http://contoh.test/beranda
Total: /* ini tercetak apa adanya */
Harga #1
Total: 75000
484 tiga-gaya.php
257 tanpa-komentar.php
741 total
121
121

Berkas pertama berukuran 484 byte dan berkas kedua 257 byte. Selisih 227 byte itu seluruhnya baris komentar beserta baris kosong di antaranya. Keduanya menghasilkan 121 byte keluaran yang identik, jadi 227 byte tadi tidak pernah sampai ke terminal atau browser.

// dan # berhenti di akhir baris, sehingga keduanya bisa dipakai di ujung baris kode seperti pada $alamat dan $total. /* */ berhenti pada penutupnya, sehingga bisa membentang beberapa baris dan dipakai untuk penjelasan panjang.

Penanda komentar hanya berlaku di luar tanda kutip. 3 baris keluaran yang memuat penanda komentar membuktikan //, /* */, dan # di dalam string diperlakukan sebagai teks biasa: URL http:// tercetak utuh, dan /* ini tercetak apa adanya */ muncul apa adanya. Aturan ini berlaku untuk kutip tunggal maupun kutip ganda.

Kesalahpahaman yang sering muncul justru sebaliknya: orang mengira // di dalam string akan memotong sisanya, lalu menambahkan escape yang tidak perlu. Kalau keluarannya sudah benar tanpa escape, escape tambahan hanya mengubah teks yang dibaca pengunjung.

Komentar blok berhenti pada penutup pertama

Dokumentasi PHP menyatakan komentar gaya C berakhir pada */ pertama yang ditemukan, dan memperingatkan agar komentar blok tidak disusun di dalam komentar blok. Berkas berikut melanggarnya tanpa sadar:

PHPPHP
<?php

/* Komentar luar
   /* Komentar dalam */
echo "Halo";
CodeTEXT
Halo

Tidak ada pesan kesalahan. Penutup pertama menutup seluruh komentar, sehingga echo "Halo"; dianggap kode biasa dan dijalankan. Ini bentuk kesalahan yang paling mahal: program berjalan, keluarannya salah, dan tidak ada peringatan yang bisa dibaca.

Kalau baris penutup asli ikut ditulis, kesalahannya baru terlihat:

PHPPHP
<?php

/* Komentar luar
   /* Komentar dalam */
echo "Halo";
*/
CodeTEXT
PHP Parse error:  syntax error, unexpected token "*", expecting end of file in /tmp/latihan-php/komentar/blok-bersarang-salah.php on line 6

expecting end of file berarti parser sudah selesai membaca seluruh perintah dan tidak mengharapkan apa pun lagi, tetapi masih menemukan tanda *. Perbaikannya: ubah komentar luar menjadi // per baris, atau hapus penutup di dalamnya. Kode yang dikomentari sebaiknya dipecah menjadi beberapa baris // supaya tidak ada penutup bersarang.

Kesalahan: komentar blok yang tidak pernah ditutup

Kebalikan dari kasus di atas, penutup yang hilang membuat parser membaca sampai akhir berkas:

PHPPHP
<?php

/* Komentar yang tidak pernah ditutup
echo "Halo";
CodeTEXT
PHP Parse error:  Unterminated comment starting line 3 in /tmp/latihan-php/komentar/blok-terbuka.php on line 3

Unterminated comment berarti komentar dibuka dan tidak ditutup sampai akhir berkas. Nomor baris yang disebut adalah baris pembuka, bukan baris terakhir. Pesan itu menunjuk awal masalah, sedangkan tempat pemeriksaan berhenti adalah ujung berkas.

Perintah php -l blok-terbuka.php melaporkan pesan yang sama, menambahkan baris Errors parsing blok-terbuka.php, dan keluar dengan kode 255. Berkas yang gagal di-parse tidak menjalankan satu baris pun, sehingga echo "Halo"; di dalamnya tidak pernah tercetak.

Cara menemukannya: hitung jumlah /* dan */ di berkas. Kalau jumlahnya tidak sama, ada blok yang tidak lengkap. Editor modern menandai pasangan yang tidak seimbang ini sebelum berkas dijalankan.

Tanda pagar yang diikuti kurung siku bukan komentar

Sejak PHP 8, atribut ditulis dengan #[. Dokumentasi PHP menyatakan deklarasi atribut dimulai dengan #[ dan diakhiri ]. Artinya #[ bukan lagi cara menulis komentar, dan isinya dibaca sebagai nama atribut.

PHPPHP
<?php

echo "Halo";
#[ini bukan komentar]
CodeTEXT
PHP Parse error:  syntax error, unexpected identifier "bukan", expecting "]" in /tmp/latihan-php/komentar/pagar-kurung.php on line 4

Pesan expecting "]" menunjukkan parser sudah menganggap #[ sebagai awal atribut dan menunggu isi yang sah di dalam kurung siku. Untuk komentar, tulis # lalu spasi, seperti pada contoh pertama bab ini. Aturan yang sama berlaku untuk # di awal baris dan di ujung baris kode.

Tag penutup di dalam komentar satu baris

Manual PHP menyatakan komentar satu baris hanya berlaku sampai akhir baris atau sampai akhir blok PHP, tergantung mana yang lebih dulu. Tag ?> mengakhiri blok PHP, dan // tidak bisa mencegahnya.

PHPPHP
<?php

// catatan: berkas ini biasanya ditutup dengan ?> di ujung
echo "Baris ini seharusnya masih dijalankan PHP", PHP_EOL;
echo "Baris terakhir", PHP_EOL;
CodeTEXT
 di ujung
echo "Baris ini seharusnya masih dijalankan PHP", PHP_EOL;
echo "Baris terakhir", PHP_EOL;

Keluarannya bukan 2 baris teks, melainkan sisa komentar dan 2 baris kode yang tercetak sebagai teks HTML. Spasi di awal keluaran adalah bagian komentar sesudah ?>. Bagian itu dikirim apa adanya karena PHP sudah keluar dari mode kode.

Komentar blok tidak punya masalah ini. Berkas yang sama dengan pembungkus /* */ menjalankan kedua echo dan mencetak 2 baris seperti yang diharapkan. Jadi bila catatanmu perlu memuat ?>, pakai komentar blok.

Docblock, komentar yang dibaca program

Docblock adalah komentar blok yang dibuka dengan /**, bukan /*. Bentuk ini dipakai IDE, alat analisis statis, dan generator dokumentasi untuk membaca tipe parameter serta nilai kembalian.

PHPPHP
<?php

/**
 * Menghitung total harga.
 *
 * @param int $harga Harga satu barang.
 * @param int $jumlah Banyak barang.
 * @return int Total sebelum pajak.
 */
function hitungTotal(int $harga, int $jumlah): int
{
    return $harga * $jumlah;
}

$fungsi = new ReflectionFunction('hitungTotal');
echo "Total: ", hitungTotal(25000, 3), PHP_EOL;
echo "Dokumentasi terbaca: ", var_export($fungsi->getDocComment() !== false, true), PHP_EOL;
echo "Jumlah baris docblock: ", substr_count($fungsi->getDocComment(), "\n"), PHP_EOL;
echo "Parameter terdokumentasi: ", count($fungsi->getParameters()), PHP_EOL;
CodeTEXT
Total: 75000
Dokumentasi terbaca: true
Jumlah baris docblock: 6
Parameter terdokumentasi: 2

ReflectionFunction::getDocComment() mengembalikan docblock sebagai string, atau false bila tidak ada. Manual menyebut tipe kembaliannya string|false. Baris terakhir menghitung parameter yang dibaca Reflection, bukan jumlah @param yang tertulis, sehingga angkanya tetap 2 walaupun satu baris dokumentasi dihapus.

Komentar biasa tidak dianggap docblock. Fungsi yang hanya diberi /* Komentar biasa */ menghasilkan false saat diperiksa dengan cara yang sama, sementara fungsi dengan /** Komentar docblock */ mengembalikan string itu apa adanya.

Komentar yang layak ditulis dan yang sebaiknya dihapus

Komentar yang mengulang kode tidak menambah informasi. Baris // kalikan harga dengan jumlah di atas $total = $harga * $jumlah; hanya memakan ruang, karena kodenya sudah menyatakan hal yang sama.

Komentar yang berguna menjelaskan alasan yang tidak terbaca dari kode: pembulatan yang disengaja, urutan pemanggilan yang harus dijaga, atau batasan API yang hanya menerima bilangan bulat. Pembaca kode bisa melihat apa yang dikerjakan sebuah baris, tetapi tidak bisa menebak mengapa baris itu ada.

PSR-12 memuat 2 aturan yang menyentuh komentar. Kurung tutup tidak boleh diikuti komentar atau perintah pada baris yang sama, dan switch yang sengaja tidak memakai break wajib diberi komentar seperti // no break agar pembaca tahu bahwa itu bukan kelalaian.

Kode mati yang diberi komentar sebaiknya dihapus, bukan disimpan sebagai catatan. Riwayat perubahan sudah tersimpan di git, sehingga mengomentari 20 baris lama hanya membuat berkas sulit dibaca. Jangan menaruh kata sandi, token, atau alamat surel pribadi di komentar: komentar dibuang saat program berjalan, tetapi tetap tersimpan di repositori dan terbaca siapa pun yang membuka berkasnya.

Latihan

3 latihan singkat untuk memastikan batas setiap gaya komentar sudah terbaca:

  1. Tulis profil.php yang mencetak namamu, beri 3 komentar dengan gaya berbeda, lalu jalankan. Keluarannya harus 1 baris tanpa pesan peringatan.
  2. Hapus satu */ dari sebuah komentar blok, jalankan php -l, catat nomor baris yang disebut, lalu kembalikan penutupnya.
  3. Tulis komentar satu baris yang memuat ?>, jalankan, lalu jelaskan mengapa keluarannya bukan yang kamu harapkan. Ulangi dengan komentar blok dan bandingkan hasilnya.

Ringkasan

Komentar dibuang sebelum program berjalan. Berkas 484 byte dengan komentar dan berkas 257 byte tanpa komentar menghasilkan 121 byte keluaran yang sama, dan selisih 227 byte itu tidak pernah sampai ke pembaca.

Setiap gaya punya batas sendiri. // dan # berhenti di akhir baris atau di ?>, sedangkan /* */ berhenti pada */ pertama sehingga tidak bisa bersarang. Docblock /** adalah bentuk khusus yang bisa dibaca Reflection lewat getDocComment(), dan komentar biasa tidak.

3 pesan yang dibahas menunjuk 3 sebab berbeda: Unterminated comment untuk penutup yang hilang, unexpected token "*" untuk penutup bersarang yang tertinggal, dan expecting "]" untuk #[ yang dikira komentar padahal awal atribut.

Referensi

  1. PHP Documentation Group. Comments.
  2. PHP Documentation Group. Attribute syntax.
  3. PHP Documentation Group. ReflectionFunctionAbstract::getDocComment.
  4. PHP-FIG. PSR-12: Extended Coding Style.