Komentar dan Gaya Kode

Kode yang benar saja belum cukup, karena kode juga harus dapat dibaca ulang oleh orang lain, termasuk oleh penulisnya sendiri beberapa bulan kemudian. Topik ini membahas dua bentuk komentar pada C, cara menulis komentar yang benar-benar berguna, konvensi penamaan yang mengikuti kebiasaan ekosistem C, dan kebiasaan pemformatan yang membuat kode mudah diikuti. Setelah membacanya, kode yang ditulis akan lebih mudah dipelihara dan lebih cepat dipahami oleh pembaca baru.

Dua bentuk komentar#

Komentar adalah bagian kode yang diabaikan kompiler sepenuhnya, sehingga isinya bebas dan keberadaannya tidak mengubah perilaku program. C menyediakan dua bentuk, yaitu komentar satu baris yang diawali // dan komentar multi-baris yang diapit /* dan */. Program berikut memakai keduanya sekaligus:

#include <stdio.h>

// Program latihan menulis komentar pada kode C.

/*
   Program menghitung sisa stok setelah penjualan.
   Stok awal dan jumlah terjual ditetapkan di awal
   agar hasilnya selalu sama setiap dijalankan.
*/
int main(void) {
    int stok = 100;
    int terjual = 35;

    int sisa = stok - terjual; // sisa dihitung sekali di awal

    printf("Sisa stok: %d\n", sisa);
    return 0;
}

Sisa stok: 65

Komentar satu baris lazim dipakai untuk catatan pendek pada satu baris atau di ujung baris kode, sedangkan komentar multi-baris lazim dipakai untuk penjelasan panjang seperti keterangan fungsi. Bentuk multi-baris memiliki satu jebakan penting, yaitu tidak bisa disarangkan (nested). Komentar berakhir pada */ pertama yang ditemui, sehingga tanda */ di dalam komentar yang lebih besar justru menutupnya lebih awal dan sisa teksnya dianggap kode:

// tidak-dijalankan
/* komentar luar /* komentar dalam */ masih dianggap kode */

Apabila kode semacam ini disimpan dan dikompilasi, kompiler menolaknya dengan pesan berikut:

salah-komentar.c:3:39: error: unknown type name ‘masih’
    3 | /* komentar luar /* komentar dalam */ masih dianggap kode */
      |                                       ^~~~~
salah-komentar.c:3:54: error: expected ‘=’, ‘,’, ‘;’, ‘asm’ or ‘__attribute__’ before ‘kode’
    3 | /* komentar luar /* komentar dalam */ masih dianggap kode */
      |                                                      ^~~~

Pesan error menunjuk kata masih karena bagian tersebut memang berada di luar komentar menurut kompiler. Karena itulah banyak tim memilih // untuk semua kebutuhan harian dan menyisakan /* */ untuk blok penjelasan yang benar-benar panjang.

Komentar yang berguna#

Komentar terbaik menjelaskan alasan (why), bukan mengulang apa yang sudah terbaca dari kode (what). Baris int sisa = stok - terjual; sudah cukup jelas tanpa komentar // menghitung sisa, tetapi komentar tentang mengapa sisa dihitung sekali di awal menambah informasi yang tidak tampak dari kodenya. Dua contoh berikut membandingkan keduanya pada baris yang sama.

// tidak-dijalankan
// tambah 1 ke penghitung lalu bandingkan dengan 10
i = i + 1;
if (i == 10) { selesai = 1; }

// tidak-dijalankan
// penghitung mulai dari 0 sehingga iterasi ke-10 adalah pembacaan terakhir
i = i + 1;
if (i == 10) { selesai = 1; }

Kedua versi menjelaskan baris yang sama, tetapi versi kedua memberi alasan yang tidak dapat ditebak dari kode. Jenis komentar lain yang berguna adalah penanda sumber aturan, misalnya merujuk spesifikasi yang menjadi dasar sebuah perhitungan, serta peringatan tentang kondisi yang tidak jelas, misalnya mengapa sebuah nilai dibatasi. Untuk keterangan di tingkat berkas, kebiasaan yang umum adalah menaruh satu komentar di bagian atas berkas untuk menjelaskan kegunaan berkas tersebut secara ringkas, sebagaimana dilakukan program komentar.c di atas.

Kebalikannya juga berlaku, yaitu kode yang sudah cukup jelas tidak perlu komentar. Nama yang bermakna membuat banyak komentar menjadi tidak diperlukan, dan komentar yang jumlahnya lebih banyak daripada kodenya biasanya tanda bahwa nama variabel perlu diperbaiki.

Konvensi penamaan#

C membedakan huruf besar dan kecil, sehingga total, Total, dan TOTAL adalah tiga nama yang berbeda. Nama hanya boleh terdiri atas huruf, angka, dan garis bawah, serta tidak boleh diawali angka. Di luar aturan bawaan bahasa, ekosistem C mengikuti kebiasaan yang hampir seragam, dan mengikutinya membuat kode terasa akrab bagi pembaca yang terbiasa dengan pustaka standar:

• Variabel dan fungsi diberi nama dengan huruf kecil dan garis bawah sebagai pemisah, misalnya stok_sisa dan hitung_total. Gaya ini dikenal sebagai snake case dan dipakai oleh seluruh pustaka standar C.
• Konstanta dan makro ditulis dengan huruf kapital, misalnya SUKU_BUNGA dan BATAS_MAKSIMUM, sehingga sifatnya yang tidak berubah terlihat dari namanya.
• Nama dibuat deskriptif namun ringkas, misalnya sisa_stok, bukan satu huruf s atau nama yang terlalu panjang.
• Huruf tunggal seperti i dan j diterima hanya untuk penghitung perulangan pendek karena kebiasaan itu telah mapan di kalangan pengembang C.

Nama yang bertentangan dengan konvensi bukanlah error, tetapi menambah beban membaca. Apabila satu berkas memuat sisaStok, Sisa_Stok, dan SISASTOK untuk hal yang serupa, pembaca akan menghabiskan waktu untuk menebak apakah ketiganya memang berbeda.

Kebiasaan kode yang mudah dibaca#

Dua program berikut menghitung hal yang sama persis, tetapi kualitas keterbacaannya berjauhan. Versi pertama valid dan berjalan benar, namun susunannya memadatkan lima pernyataan dalam satu baris dengan nama satu huruf:

#include <stdio.h>
int main(void){int s=100;int t=35;int h=s-t;printf("Sisa stok: %d\n",h);return 0;}

Sisa stok: 65

Versi kedua memuat logika yang sama dengan nama yang jelas, satu pernyataan per baris, dan indentasi yang konsisten:

#include <stdio.h>

int main(void) {
    int stok_awal = 100;
    int stok_terjual = 35;

    int stok_sisa = stok_awal - stok_terjual;

    printf("Sisa stok: %d\n", stok_sisa);
    return 0;
}

Sisa stok: 65

Keluaran keduanya identik, dan justru itulah intinya, yaitu kerapian kode tidak mengorbankan perilaku. Kebiasaan yang tampak pada versi kedua dapat dirangkum sebagai berikut:

• Satu pernyataan per baris, sehingga kesalahan pada baris mana pun mudah ditunjuk pesan error.
• Indentasi empat spasi untuk setiap tingkat kurung kurawal agar struktur terlihat sekilas.
• Baris kosong di antara kelompok pernyataan yang mengerjakan langkah berbeda.
• Kurung kurawal selalu ditulis meskipun isinya satu pernyataan, sehingga penambahan baris baru tidak salah tempat.
• Angka penting diberi nama const, mengikuti kebiasaan pada topik Konstanta dan Literal, alih-alih dibiarkan menjadi angka misterius.

Kesalahan umum#

Kesalahan pertama adalah membiarkan kode mati, yaitu blok kode lama yang hanya dilumpuhkan dengan komentar demi jaga-jaga. Kode semacam itu cepat basi, tidak ikut diuji, dan menambah kebisingan, sehingga lebih baik dihapus karena riwayat perubahan kode dapat disimpan dengan alat version control.

Kesalahan kedua adalah komentar yang kedaluwarsa, yaitu komentar yang isinya sudah tidak sesuai kode setelah kode direvisi. Komentar yang salah lebih membahayakan daripada tidak ada komentar, sehingga setiap revisi kode wajib menyertakan pemeriksaan komentar di sekitarnya.

Kesalahan ketiga adalah mencampur gaya pemformatan dalam satu berkas, misalnya sebagian fungsi memakai indentasi tab dan sebagian lagi memakai spasi. Perbedaan yang tampak sepele ini membuat perbedaan revisi antar berkas menjadi bising dan menyembunyikan perubahan yang sebenarnya. Pilih satu gaya sejak berkas pertama dibuat dan pertahankan sampai akhir berkas.

Ringkasan#

• Komentar // berlaku satu baris dan /* */ berlaku multi-baris, dengan jebakan bahwa bentuk multi-baris tidak dapat disarangkan.
• Komentar yang berguna menjelaskan alasan dan sumber aturan, bukan mengulang isi baris kodenya.
• Penamaan mengikuti kebiasaan ekosistem C, yaitu snake case untuk variabel dan fungsi serta huruf kapital untuk konstanta.
• Satu pernyataan per baris, indentasi konsisten, kurung kurawal yang selalu ditulis, dan nama yang bermakna membuat kode mudah dibaca tanpa mengubah perilakunya.

Referensi#

• Comments — cppreference — Dokumentasi bentuk komentar C beserta catatan perilaku tidak tersarangnya.
• Warning Options — GNU Compiler Collection — Opsi peringatan gcc seperti -Wall dan -Wcomment yang membantu menegakkan kualitas kode.