08. Comment dan catatan untuk dirimu sendiri

Kamu sudah mengenal comment sebentar di Bab 07: teks yang diabaikan Python saat menjalankan file. Comment memungkinkanmu meninggalkan catatan untuk programmer yang paling pelupa yang pernah kamu kenal — dirimu sendiri, minggu depan. Comment yang baik mengubah dinding kode menjadi sesuatu yang bisa kamu baca kembali.

Dua jenis comment

Sebuah comment satu baris dimulai dengan #. Semua dari sana hingga akhir baris diabaikan:

# This whole line is a note for a human.
print("Hi")          # A note can also sit after some code.

Untuk blok catatan multi-baris, gunakan beberapa baris # berturut-turut, atau gunakan string triple-quoted (""" atau '''). String triple-quoted yang tidak ditetapkan ke apa pun diabaikan oleh Python saat runtime, membuatnya berguna sebagai blok comment:

"""
This is a longer note. It can run for several lines.
Python ignores it because nothing uses the value.
"""
print("Still runs.")

Gunakan baris # tunggal untuk catatan pendek dan untuk mengkomentari satu baris kode. Gunakan blok """ untuk paragraf di bagian atas file atau penjelasan yang lebih panjang.

Buka exercises/08/01-comment-styles.py. File ini punya tiga panggilan print. Tambahkan comment # satu baris di atas yang pertama, comment di akhir baris setelah yang kedua, dan blok """ di bagian atas yang menjelaskan file ini. Jalankan — outputnya tidak boleh berubah.

Comment mengapa, bukan apa

Kesalahan paling umum pada pemula adalah comment yang hanya mengulang kode:

score = 0       # set score to 0
score = score + 10  # add 10 to score

Comment itu tidak menambahkan apa pun — kodenya sudah mengatakan apa yang dilakukannya. Comment yang berguna menjelaskan mengapa, atau memperingatkan tentang sesuatu yang mengejutkan:

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

Aturan yang bagus: kalau comment dan kode mengatakan hal yang sama, hapus comment-nya. Simpan untuk mengapa, gotcha, dan hal yang tidak jelas.

Mengkomentari kode

Comment punya pekerjaan kedua: mematikan kode tanpa menghapusnya — salah satu trik debugging paling berguna.

Misalkan sebuah program berperilaku salah dan kamu mencurigai satu baris. Taruh # di depannya dan jalankan lagi:

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

Sekarang "Step 2" tidak pernah dicetak. Kalau masalahnya hilang, kamu menemukan pelakunya. Untuk mengaktifkan kembali baris tersebut, hapus # — lebih cepat dan lebih aman daripada menghapus dan mengetik ulang nanti.

Untuk mematikan seluruh blok, taruh # di depan setiap baris, atau bungkus dengan blok """:

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

Jangan taruh penutup """ di dalam teks blok. """ pertama yang dilihat Python mengakhiri string triple-quoted, dan apa pun yang mengikutinya diperlakukan sebagai kode lagi — biasanya menyebabkan error. Simpan penutup """ di barisnya sendiri di akhir.

Header untuk setiap file

Kebiasaan yang layak dibangun: mulai setiap file dengan blok comment pendek yang menjelaskan untuk apa file itu. Dirimu di masa depan akan berterima kasih kepada dirimu sekarang.

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

print("Welcome!")

Pekerjaan Rumah

File pekerjaan rumah ada di exercises/08/homework/.

Soal 1 — Beri anotasi pada program

Buka exercises/08/homework/01-annotate.py. File ini punya beberapa baris kode yang berfungsi tanpa comment. Tambahkan header """ yang menjelaskan apa yang dilakukan file, ditambah minimal dua comment # satu baris yang menjelaskan mengapa sebuah baris ada di sana (bukan apa yang dilakukannya). Output tidak boleh berubah.

Soal 2 — Temukan bug dengan mengkomentari

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

start
end

Lakukan dengan menambahkan #, bukan dengan menghapus barisnya.

Soal 3 — Matikan sebuah blok

Buka exercises/08/homework/03-block-off.py. Menggunakan satu blok comment """, 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.py. File ini penuh dengan comment yang tidak berguna karena hanya mengulang kode. Tulis ulang setiap comment agar menjelaskan mengapa baris itu ada, atau hapus kalau tidak ada yang berguna untuk dikatakan. Targetkan comment yang lebih sedikit tapi lebih baik.

Stuck atau sudah selesai? Buka halaman solusi pekerjaan rumah.