08. Komentar dan catatan untuk dirimu sendiri

Kamu sudah sedikit berkenalan dengan komentar di Bab 07: teks yang diabaikan Lua saat menjalankan file. Komentar berguna untuk meninggalkan catatan bagi programmer paling pelupa yang pernah kamu ajak kerja sama — dirimu sendiri, minggu depan. Komentar yang bagus mengubah tumpukan kode yang membingungkan menjadi sesuatu yang bisa dibaca lagi.

Dua jenis komentar

Komentar satu baris dimulai dengan dua tanda hubung --. Semua teks dari situ sampai akhir baris akan diabaikan:

-- Baris ini seluruhnya adalah catatan untuk manusia.
print("Hi")          -- Catatan juga bisa diletakkan setelah kode.

Komentar multi-baris dimulai dengan --[[ dan diakhiri dengan ]]. Lua mengabaikan semua teks di antara keduanya, sebanyak baris yang kamu mau:

--[[
  Ini adalah catatan yang lebih panjang. Bisa terdiri dari beberapa baris.
  Lua mengabaikan semuanya sampai penanda penutup.
]]
print("Still runs.")

Gunakan komentar satu baris untuk catatan singkat, dan komentar multi-baris untuk paragraf di bagian atas file atau penjelasan yang lebih panjang.

Buka exercises/08/01-comment-styles.lua. Ada tiga pemanggilan print di sana. Tambahkan komentar satu baris di atas yang pertama, komentar di akhir baris setelah yang kedua, dan komentar multi-baris di bagian atas file yang menjelaskan isi file tersebut. Jalankan — keluarannya tidak boleh berubah.

Komentari mengapa, bukan apa

Kesalahan paling umum bagi pemula adalah komentar yang hanya mengulang kode itu sendiri:

local score = 0     -- set score to 0
score = score + 10  -- add 10 to score

Komentar seperti itu tidak berguna — kode sudah menjelaskan sendiri apa yang dilakukannya. Komentar yang berguna menjelaskan mengapa, atau memberi peringatan tentang sesuatu yang tidak terduga:

local score = 0       -- players always start a round on zero
score = score + 10    -- bonus for finishing under par

Aturan yang bagus: kalau komentar dan kode mengatakan hal yang sama, hapus komentar itu. Simpan komentar untuk mengapa, jebakan tersembunyi, dan hal yang tidak langsung terlihat.

Mematikan kode dengan komentar

Komentar punya kegunaan kedua: mematikan kode tanpa menghapusnya — salah satu trik debugging paling berguna yang ada.

Misalnya sebuah program bermasalah dan kamu curiga ada satu baris penyebabnya. Tambahkan -- di depan baris itu lalu jalankan lagi:

print("Step 1")
-- print("Step 2")
print("Step 3")

Sekarang "Step 2" tidak pernah dicetak. Kalau masalahnya hilang, kamu sudah menemukan penyebabnya. Untuk mengaktifkan baris itu kembali, hapus -- — lebih cepat dan lebih aman daripada menghapus lalu mengetiknya ulang nanti.

Untuk mematikan satu blok sekaligus, bungkus dengan --[[ dan ]]:

--[[
print("These three")
print("lines are")
print("all switched off")
]]
print("Only this line runs.")

Jangan letakkan tanda penutup ]] di dalam teks komentar multi-baris. ]] pertama yang dilihat Lua akan mengakhiri komentar, dan semua teks setelahnya dianggap sebagai kode lagi — dan biasanya menyebabkan error. Letakkan ]] di barisnya sendiri di bagian akhir.

Header untuk setiap file

Kebiasaan yang layak dibangun: mulai setiap file dengan komentar multi-baris singkat yang menjelaskan tujuan file tersebut. Dirimu di masa depan akan berterima kasih pada dirimu sekarang.

--[[
  Greeting program.
  Asks for nothing; just prints a friendly welcome banner.
  Written while learning Chapter 08.
]]

print("Welcome!")

PR (Pekerjaan Rumah)

File PR ada di exercises/08/homework/.

Soal 1 — Beri anotasi pada sebuah program

Buka exercises/08/homework/01-annotate.lua. Ada beberapa baris kode yang berfungsi tanpa komentar sama sekali. Tambahkan header multi-baris yang menjelaskan apa yang dilakukan file tersebut, ditambah setidaknya dua komentar satu baris yang menjelaskan mengapa sebuah baris ada di sana (bukan apa yang dilakukannya). Keluarannya tidak boleh berubah.

Soal 2 — Temukan bug dengan cara mematikan kode

Buka exercises/08/homework/02-comment-out.lua. Salah satu baris print-nya menghasilkan keluaran yang seharusnya tidak ada. Matikan tepat satu baris sehingga program hanya mencetak:

start
end

Lakukan dengan menambahkan --, bukan dengan menghapus barisnya.

Soal 3 — Matikan satu blok

Buka exercises/08/homework/03-block-off.lua. Dengan menggunakan satu komentar multi-baris --[[ ]], matikan tiga baris print di tengah sehingga hanya baris pertama dan terakhir yang dicetak. Jalankan untuk memastikan.

Tantangan — Mengapa, bukan apa

Buka exercises/08/homework/04-why-not-what.lua. File ini penuh dengan komentar tidak berguna yang hanya mengulang kode. Tulis ulang setiap komentar agar menjelaskan mengapa baris tersebut ada, atau hapus jika tidak ada yang berguna untuk dikatakan. Targetkan komentar yang lebih sedikit tapi lebih bermutu.

Mentok atau sudah selesai? Buka halaman solusi PR.