Cara Menulis Komentar Pada PHP Dengan Baik

Seperti pada bahasa pemrograman pada umum nya, kita juga dapat menulis komentar pada PHP, pada kesempatan kali ini kita akan membahas cara membuat/menulis komentar pada PHP.

Pentingnya Komentar

Kenapa komentar ini penting? komentar pada PHP dan bahasa pemrograman pada umumnya penting untuk memberi catatan kode yang ditulis.

Beberapa hal yang membuat penulisan komentar menjadi penting:

• Jika kita menulis suatu script kemudian beralih ke kode lain, mungkin setelah satu atau dua minggu, jika kita kembali ke kode sebelumnya, kita masih dapat mengingatnya.

  Namun, setelah beberapa bulan atau bahkan tahun, maka akan sulit diingat lagi apa yang telah kita lakukan.

• Jika script yang kita buat kita share ke public, maka komentar akan memudahkan programmer lain memahami kode yang kita buat.

  Bahkan pada programmer / aplikasi profesional, umumnya script yang kita buat komentar yang ditulis bisa melebihi jumlah kode yang ditulis.

• Disamping itu, pada Repository tertentu seperti PEAR, Framework, dan CMS tertentu seperti WordPress, penulisan komentar ini wajib di tulis untuk menandai bagian tertentu yang akan dibaca aplikasi.

Cara Membuat / Menulis Komentar Pada PHP

Setelah mengetahui pentingnnya komentar, mari kita bahas cara membuat komentar di PHP.

Pada PHP, komentar dibagi menjadi dua yaitu komentar per baris / single-line / inline comment dan  komentar yang terdiri dari beberapa baris / multi-line comment.

Penulisan komentar ini (baik inline maupun multiline) dapat dilakukan dimana saja asal didalam open tag (<?php atau <?= )

1 Menulis Komentar Pada PHP Per Baris (inline-comment)

Untuk menulis komentar yang hanya terdiri dari satu baris, maka kita bisa menggunakan tanda // (Model C++) atau tanda # (Model Unix Shell)

Ketika PHP menemukan tanda ini ( // ), maka mengabaikan (tidak akan memproses) tanda tersebut beserta semua karakter yang ada setelahnya sampai bertemu dengan baris baru atau bertemu dengan close tag ( ?> ).

Contoh penulisan:

<?php
//--------------------------
// Form Login
//--------------------------

$email = isset($_POST['email']) ? $_POST['email'] : '';
?>
<h2>Form Login</h2>
<form method="post" action="">
	<input type="text" name="email" value="<?=$email // Jika tombol Log In diklik ?>"/>
	<input type="text" name="password"/>
	<input type="submit" name="submit" value="Log In"/>
</form>

<?php
//--------------------------
// Validasi Form Login
//--------------------------

if (isset($_POST['submit'])) {
	
	// Jika email dan password tidak diisi
	if ($_POST['email'] == '' || $_POST['password'] == '') {
		echo 'Email dan Password harus diisi';
	} else {
		// Validasi username dan password
		$sql = 'SELECT user_name 
				FROM user 
				WHERE email = ' . $_POST['email'] . ' 
						AND password = ' . $_POST['password']; 
	}
}

Sama seperti model C++, pada penulisan komentar model unix shell ini, PHP akan mengabaikan (tidak memproses) tanda # beserta semua karakter yang mengikutinya, sampai akhir baris tersebut  atau sampai bertemu dengan close tag ( ?> ).

Contoh  penulisan:

###########################
# Validasi Form Login
###########################

if (isset($_POST['submit'])) {
	# Jika email dan password tidak diisi
	if (!$_POST['uname'] || !$_POST['pass']) {
		echo 'Username dan Password tidak boleh kosong';
	} else {
		# Validasi username dan password
		$sql = 'SELECT uname 
				FROM tb_user 
				WHERE uname = ' . $_POST['uname'] . ' 
						AND password = ' . $_POST['pass']; 
	}
}

2 Menulis Komentar Pada PHP Lebih dari Satu Baris

Untuk membuat komentar pada PHP beberapa baris / multi-line comment, kita menggunakan tanda /* sebagai pembuka dan */ sebagai penutup. Model ini disebut model C.

Pada komentar model ini, PHP akan mengabaikan (tidak memproses) tanda  /*  dan semua karakter yang mengikutinya hingga menemukan tanda  */, berapapun banyaknya jumlah baris.

Sehingga, jenis komentar ini cocok digunakan untuk menulis komentar yang panjang yang terdiri lebih dari satu baris

Tidak ada standar untuk penulisan komentar jenis ini, namun yang umum digunakan adalah seperti yang di standarkan oleh Zend Framework dan PHPDoc, yaitu:

/** <-- diawali
* Komentar
*/  <-- diakhiri

Maka ketika kita melihat source code beberapa program yang populer, kita akan sering menemukan komentar jenis ini dibagian header (baris paling atas).

Contoh penulisan:

<?php
/**
	Fungsi ini berguna untuk memotong kalimat dengan tidak memotong kata
	-- Argumen pertama berisi kalimat yang ingin dipotong
	-- Argumen pertama berisi jumlah huruf yang ingin dipotong
	-- Argumen kedua diisi apakah kata terakhir diambil atau di buang	
*/

function cutText( $kalimat, $jml_huruf, $pembulatan = true)
{
	/* Hitung jumlah huruf */
	$len = strlen ($jml_huruf);
	
	// kode berikutnya
}

Menonaktifkan baris tertentu

Penulisan komentar model ini juga sering digunakan untuk menonaktifkan baris kode tertentu dengan membuat kode pada baris tersebut menjadi komentar, sehingga diabaikan oleh PHP, misal:

<?php
/**
* Validasi Form Login
*/

if (isset($_POST['submit'])) {
	// Jika email dan password tidak diisi
	if (!$_POST['uname'] || !$_POST['pass']) {
		echo 'Username dan Password tidak bole kosong';
	} else {
		// Validasi username dan password
		/* $sql = 'SELECT uname 
				FROM tb_user 
				WHERE uname = ' . $_POST['uname'] . ' 
						AND password = ' . $_POST['pass'];  */
						
		if ($_POST['uname'] == 'prawoto.hadi@gmail.com') {
			// Kode berikutnya
		}
	}
}

Pada kode diatas, baris 12 – 15 kita nonaktifkan (pada notepad++ dengan shortcut Ctrl + Shift + Q). Selanjutnya variabel $_POST['uname']  kita definisikan dengan nilai tertentu.

Hal ini sering kita lakukan untuk bagian tertentu dari aplikasi yang sedang kita kembangkan.

3 Model Komentar Yang Sebaiknya Digunakan

Jadi, dari ketiga model komentar diatas, maka yang harus digunakan?

Demikian pembahasan mengenai cara menulis komentar pada PHP, semoga bermanfaat.