15 Latihan Terbaik untuk Menulis Kode Yang Sangat Mudah Dibaca

() translation by (you can also view the original English article)

Dua kali dalam sebulan, kami meninjau kembali beberapa postingan favorit para pembaca dari riwayat Nettuts+.

Keterbacaan kode merupakan topik universal di dunia pemrograman komputer. Ini adalah salah satu hal yang harus kita pelajari sebagai pengembang. Artikel ini akan memberikan detail 15 praktik terbaik ketika ingin menulis kode yang mudah dibaca.

1- Mengomentari & Mendokumentasi

IDE ( Integrated Development Environment ) sudah berkembang jauh dalam beberapa tahun terakhir. Ini membuat komentar pada kode anda lebih berguna daripada sebelumnya. Standar tertentu dalam komentar anda memungkinkan IDE dan alat lain untuk memanfaatkannya dalam hal yang berbeda.

Perhatikan contoh ini:

Komentar yang saya tambahkan pada fungsi dapat ditampilkan setiap kali saya menggunakan fungsi itu, bahkan pada file yang berbeda.

Ini adalah contoh lain di mana saya memanggil fungsi dari library pihak ketiga:

Dalam contoh-contoh tertentu, tipe komentar ( atau dokumentasi ) yang digunakan adalah basis dari PHPDoc, dan IDE seperti Aptana.

2- Indentasi Yang Konsisten

Saya anggap anda sudah paham bahwa anda harus memberikan indentasi pada kode anda. Namun, itu juga perlu diperhatikan apa itu merupakan ide yang baik untuk tetap memakai indentasi yang konsisten.

Ada lebih dari satu cara dalam mengindentasi kode.

Gaya 1:


function foo() {
  if ($maybe) {
		do_it_now();
		again();
	} else {
		abort_mission();
	}
	finalize();
}

Gaya 2:


function foo()
{
	if ($maybe)
	{
		do_it_now();
		again();
	}
	else
	{
		abort_mission();
	}
	finalize();
}

Gaya 3:


function foo()
{	if ($maybe)
	{	do_it_now();
		again();
	}
	else
	{	abort_mission();
	}
	finalize();
}

Saya menggunakan gaya ke-2 pada kode saya tapi terkadang berubah menjadi yang ke-1 Tapi itu hanya masalah preferensi. Tidak ada yang namanya gaya "terbaik" yang harus semua orang ikuti. Sebenarnya, gaya terbaik, adalah gaya yang konsisten. Jika anda merupakan bagian dari tim atau jika anda berkontribusi pada sebuah proyek, anda harus mengikuti gaya yang ada dalam proyek itu.

Gaya indentasi tidak benar-benar berbeda satu sama lainnya. Terkadang, mereka mencampurkan aturan yang berbeda. Misalnya, pada PEAR Coding Standards, kurung kurawal yang terbuka "{" berada pada baris yang sama sebagai struktur kontrol, tapi mereka melewatinya ke baris selanjutnya setelah definisi fungsi.

Gaya PEAR:


function foo()
{                     // placed on the next line
    if ($maybe) {     // placed on the same line
        do_it_now();
        again();
    } else {
        abort_mission();
    }
    finalize();
}

Perhatikan juga bahwa mereka menggunakan empat spasi, bukan tab untuk indentasi.

Berikut adalah artikel Wikipedia dengan contoh gaya indentasi yang berbeda.

3 - Hindari Komentar yang Jelas

Mengomentari kode Anda adalah sangat fantastis; namun, bisa jadi berlebihan atau hanya terlalu berlebihan. Ambil contoh ini:


// get the country code
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);

// if country code is US
if ($country_code == 'US') {

	// display the form input for state
	echo form_input_state();
}

Bila teksnya sudah jelas, sebenarnya tidak produktif untuk mengulanginya dalam komentar.

Jika Anda harus mengomentari kode itu, Anda dapat menggabungkannya ke satu baris saja:


// display state selection for US users
$country_code = get_country_code($_SERVER['REMOTE_ADDR']);
if ($country_code == 'US') {
	echo form_input_state();
}

4 - Pengelompokan Kode

Lebih sering daripada tidak, tugas tertentu memerlukan beberapa baris kode. Sebaiknya simpan tugas ini di dalam blok kode yang terpisah, dengan beberapa spasi di antaranya.

Berikut adalah contoh yang disederhanakan:



// get list of forums
$forums = array();
$r = mysql_query("SELECT id, name, description FROM forums");
while ($d = mysql_fetch_assoc($r)) {
	$forums []= $d;
}

// load the templates
load_template('header');
load_template('forum_list',$forums);
load_template('footer');

Menambahkan komentar di awal setiap blok kode juga menekankan pemisahan visual.

5 - Skema Penamaan yang Konsisten

PHP sendiri terkadang bersalah karena tidak mengikuti skema penamaan yang konsisten:

strpos() vs str_split()
imagetypes() vs image_type_to_extension()

Pertama-tama, nama harus memiliki batas kata. Ada dua pilihan populer:

camelCase: Huruf pertama dari setiap kata dikapitalisasi, kecuali kata pertama.
underscore: Underscore antara kata-kata, seperti: mysql_real_escape_string().

Memiliki pilihan yang berbeda menciptakan situasi yang mirip dengan gaya indentasi, seperti yang saya sebutkan sebelumnya. Jika proyek yang ada mengikuti konvensi tertentu, Anda harus melakukannya dengan itu. Selain itu, beberapa platform bahasa cenderung menggunakan skema penamaan tertentu. Misalnya, di Java, kebanyakan kode menggunakan nama camelCase, sedangkan di PHP, mayoritas menggunakan underscore.

Ini juga bisa dicampur. Beberapa pengembang lebih suka menggunakan underscore untuk fungsi prosedural, dan nama kelas, tapi menggunakan camelCase untuk nama metode kelas:


class Foo_Bar {

	public function someDummyMethod() {

	}

}

function procedural_function_name() {

}

Jadi sekali lagi, tidak ada gaya "terbaik" yang jelas. Hanya bersikaplah konsisten.

6 - Prinsip DRY

DRY singkatan dari Don't Repeat Yourself. Juga dikenal sebagai DIE: Duplication is Evil.

Prinsipnya menyatakan:

"Setiap potongan pengetahuan harus memiliki representasi otoritatif tunggal, tidak ambigu di dalam sebuah sistem."

Tujuan sebagian besar aplikasi (atau komputer pada umumnya) adalah mengotomatisasi tugas yang berulang. Prinsip ini harus dijaga dalam semua kode, bahkan aplikasi web. Bagian kode yang sama tidak boleh diulang berkali-kali.

Misalnya, sebagian besar aplikasi web terdiri dari banyak halaman. Ini sangat mungkin bahwa halaman-halaman ini akan berisi elemen umum. Header dan footer biasanya merupakan kandidat terbaik untuk ini. Bukanlah ide yang bagus untuk tetap menyalin menempel header dan footer ini ke setiap halaman. Berikut ini Jeffrey Way menjelaskan cara membuat template di CodeIgniter.


$this->load->view('includes/header');

$this->load->view($main_content);

$this->load->view('includes/footer');

7 - Hindari Persarangan yang Dalam

Terlalu banyak tingkat persarangan bisa membuat kode lebih sulit dibaca dan diikuti.


function do_stuff() {

// ...

	if (is_writable($folder)) {

		if ($fp = fopen($file_path,'w')) {

			if ($stuff = get_some_stuff()) {

				if (fwrite($fp,$stuff)) {

					// ...

				} else {
					return false;
				}
			} else {
				return false;
			}
		} else {
			return false;
		}
	} else {
		return false;
	}
}

Demi keterbacaan, biasanya memungkinkan untuk membuat perubahan pada kode Anda untuk mengurangi tingkat persarangan:


function do_stuff() {

// ...

	if (!is_writable($folder)) {
		return false;
	}

	if (!$fp = fopen($file_path,'w')) {
		return false;
	}

	if (!$stuff = get_some_stuff()) {
		return false;
	}

	if (fwrite($fp,$stuff)) {
		// ...
	} else {
		return false;
	}
}

8 - Batas Panjang Baris

Mata kita lebih nyaman saat membaca kolom teks yang tinggi dan sempit. Inilah alasan mengapa artikel surat kabar terlihat seperti ini:

Adalah praktik yang baik untuk menghindari penulisan baris kode yang memanjang secara horisontal.



// bad
$my_email->set_from('test@email.com')->add_to('programming@gmail.com')->set_subject('Methods Chained')->set_body('Some long message')->send();

// good
$my_email
	->set_from('test@email.com')
	->add_to('programming@gmail.com')
	->set_subject('Methods Chained')
	->set_body('Some long message')
	->send();

// bad
$query = "SELECT id, username, first_name, last_name, status FROM users LEFT JOIN user_posts USING(users.id, user_posts.user_id) WHERE post_id = '123'";

// good
$query = "SELECT id, username, first_name, last_name, status
	FROM users
	LEFT JOIN user_posts USING(users.id, user_posts.user_id)
	WHERE post_id = '123'";

Juga, jika ada yang ingin membaca kode dari jendela terminal, seperti pengguna Vim, ada baiknya membatasi panjang baris menjadi sekitar 80 karakter.

9 - Organisasi File dan Folder

Secara teknis, Anda bisa menulis keseluruhan kode aplikasi dalam satu file. Tapi itu akan menjadi mimpi buruk untuk dibaca dan dipelihara.

Selama proyek pemrograman pertama saya, saya tahu tentang gagasan dari penciptaan "include files." Namun, saya bahkan belum benar-benar teratur. Saya membuat folder "inc", dengan dua file di dalamnya: db.php dan functions.php. Seiring bertumbuhnya aplikasi, file fungsi juga menjadi sangat besar dan sulit dipelihara.

Salah satu pendekatan terbaik adalah dengan menggunakan kerangka kerja, atau meniru struktur folder mereka. Seperti inilah CodeIgniter:

10 - Nama Sementara yang Konsisten

Biasanya, variabel harus deskriptif dan mengandung satu atau beberapa kata. Tapi, ini tidak selalu berlaku untuk variabel sementara. Mereka bisa sesingkat karakter tunggal.

Ini adalah praktik yang baik untuk menggunakan nama yang konsisten untuk variabel sementara Anda yang memiliki peran yang sama. Berikut adalah beberapa contoh yang cenderung saya gunakan dalam kode saya:



// $i for loop counters
for ($i = 0; $i < 100; $i++) {

	// $j for the nested loop counters
	for ($j = 0; $j < 100; $j++) {

	}
}

// $ret for return variables
function foo() {
	$ret['bar'] = get_bar();
	$ret['stuff'] = get_stuff();

	return $ret;
}

// $k and $v in foreach
foreach ($some_array as $k => $v) {

}

// $q, $r and $d for mysql
$q = "SELECT * FROM table";
$r = mysql_query($q);
while ($d = mysql_fetch_assocr($r)) {

}

// $fp for file pointers
$fp = fopen('file.txt','w');

11 - Menggunakan Huruf Besar Kata-kata Khusus SQL

Interaksi database adalah bagian besar dari sebagian besar aplikasi web. Jika Anda menulis kueri SQL mentah, adalah ide bagus untuk membuatnya tetap terbaca juga.

Meskipun kata-kata khusus SQL dan nama fungsi tidak peka terhadap huruf besar, praktik yang umum adalah menggunakan huruf besar untuk membedakannya dari nama tabel dan kolom Anda.


SELECT id, username FROM user;

UPDATE user SET last_login = NOW()
WHERE id = '123'

SELECT id, username FROM user u
LEFT JOIN user_address ua ON(u.id = ua.user_id)
WHERE ua.state = 'NY'
GROUP BY u.id
ORDER BY u.username
LIMIT 0,20

12 - Pemisahan Kode dan Data

Ini adalah prinsip lainnya yang berlaku untuk hampir semua bahasa pemrograman di semua lingkungan. Dalam kasus pengembangan web, "data" biasanya menyiratkan output HTML.

Ketika PHP pertama kali dirilis bertahun-tahun yang lalu, ia terutama dilihat sebagai mesin template. Sudah umum untuk memiliki file HTML yang besar dengan beberapa baris kode PHP di antaranya. Namun, hal-hal telah berubah selama bertahun-tahun dan situs web menjadi lebih dan lebih dinamis dan fungsional. Kode sekarang menjadi bagian besar dari aplikasi web, dan bukan lagi praktik yang bagus untuk menggabungkannya dengan HTML.

Anda bisa menerapkan prinsip ini pada aplikasi Anda sendiri, atau Anda dapat menggunakan alat pihak ketiga (mesin template, kerangka kerja atau CMS) dan mengikuti konvensi mereka.

Kerangka PHP Populer:

Mesin Template Populer:

Sistem Manajemen Konten Populer

13 - Sintaks Alternatif di Dalam Template

Anda dapat memilih untuk tidak menggunakan mesin template mewah, dan sebaliknya pergi dengan PHP inline biasa di file template Anda. Ini tidak harus melanggar "Pemisahan Kode dan Data", asalkan kode inline berhubungan langsung dengan keluaran, dan dapat dibaca. Dalam hal ini Anda harus mempertimbangkan untuk menggunakan sintaks alternatif untuk struktur kontrol.

Inilah contohnya:


<div class="user_controls">
	<?php if ($user = Current_User::user()): ?>
		Hello, <em><?php echo $user->username; ?></em> <br/>
		<?php echo anchor('logout', 'Logout'); ?>
	<?php else: ?>
		<?php echo anchor('login','Login'); ?> |
		<?php echo anchor('signup', 'Register'); ?>
	<?php endif; ?>
</div>

<h1>My Message Board</h1>

<?php foreach($categories as $category): ?>

	<div class="category">

		<h2><?php echo $category->title; ?></h2>

		<?php foreach($category->Forums as $forum): ?>

			<div class="forum">

				<h3>
					<?php echo anchor('forums/'.$forum->id, $forum->title) ?>
					(<?php echo $forum->Threads->count(); ?> threads)
				</h3>

				<div class="description">
					<?php echo $forum->description; ?>
				</div>

			</div>

		<?php endforeach; ?>

	</div>

<?php endforeach; ?>

Ini memungkinkan Anda menghindari banyak kurung kurawal. Selain itu, kodenya terlihat dan terasa mirip dengan cara HTML terstruktur dan terindentasi.

14 - Berorientasi Objek vs Prosedural

Pemrograman berorientasi objek dapat membantu Anda membuat kode yang terstruktur dengan baik. Tapi itu tidak berarti Anda harus meninggalkan pemrograman prosedural sepenuhnya. Sebenarnya membuat perpaduan kedua gaya tersebut adalah bagus.

Objek harus digunakan untuk mewakili data, biasanya berada dalam database.


class User {

	public $username;
	public $first_name;
	public $last_name;
	public $email;

	public function __construct() {
		// ...
	}

	public function create() {
		// ...
	}

	public function save() {
		// ...
	}

	public function delete() {
		// ...
	}

}

Fungsi prosedural dapat digunakan untuk tugas-tugas tertentu yang dapat dilakukan secara independen.


function capitalize($string) {

	$ret = strtoupper($string[0]);
	$ret .= strtolower(substr($string,1));
	return $ret;

}

15 - Membaca Kode Open Source

Proyek Open Source dibangun dengan masukan dari banyak pengembang. Proyek-proyek ini perlu mempertahankan tingkat keterbacaan kode yang tinggi sehingga tim dapat bekerja sama seefisien mungkin. Oleh karena itu, ada baiknya menelusuri kode sumber proyek-proyek ini untuk mengamati apa yang sedang dilakukan pengembang ini.

16 - Refactoring Kode

Saat Anda "refactor," Anda membuat perubahan pada kode tanpa mengubah fungsinya. Anda bisa menganggapnya seperti "membersihkan," demi meningkatkan keterbacaan dan kualitas.

Ini tidak termasuk perbaikan bug atau penambahan fungsi baru apapun. Anda mungkin melakukan refactor pada kode yang telah Anda tulis sehari sebelumnya, sementara masih segar di kepala Anda, sehingga lebih mudah dibaca dan dapat digunakan kembali saat Anda berpotensi melihatnya dua bulan dari sekarang. Seperti moto mengatakan: "refactor awal, refactor sering."

Anda dapat menerapkan salah satu "praktik terbaik" dari keterbacaan kode selama proses refactoring.

Saya harap Anda menikmati artikel ini! Apa saja yang saya lewatkan? Beri tahu saya lewat komentar.