Komentar di Python: satu baris, banyak baris, dan docstring

Komentar itu untuk manusia

Python mengabaikan komentar. Itulah intinya. Apa pun yang kamu tandai sebagai komentar tidak terlihat oleh interpreter; komentar ada semata-mata untuk orang yang membaca kodemu, yang biasanya adalah dirimu sendiri enam bulan lagi, bertanya-tanya apa yang dulu kamu pikirkan.

Meski begitu, komentar yang hanya mengulang apa yang jelas dilakukan kode tidak layak ditulis. Komentar terbaik menjelaskan kenapa: sebuah batasan, solusi sementara, atau keputusan yang tidak terlihat jelas dari kodenya sendiri. Kodenya sudah memberitahumu apa yang terjadi.

Komentar satu baris dengan #

Bentuk dasarnya adalah # diikuti catatanmu:

# Calculate the tax portion of the total.
total = 100
tax = total * 0.08
print(tax)

Kamu juga bisa menambahkan komentar pendek di akhir sebuah baris. Menurut konvensi, sisakan paling sedikit dua spasi sebelum #:

refresh_interval = 300  # seconds; keep in sync with the dashboard config
print(refresh_interval)

Python membaca # di mana saja di luar string dan memperlakukan sisa barisnya sebagai komentar. Bagian "di luar string" itu penting: # di dalam tanda kutip hanyalah sebuah karakter.

url = "https://example.com/#section-2"  # the real comment starts here
print(url)

#section-2 di dalam string adalah bagian dari URL. Python baru masuk ke mode "komentar" untuk # setelah string-nya ditutup.

Mengomentari banyak baris

Python tidak punya komentar blok /* */. Untuk melewati beberapa baris, taruh # di awal setiap baris:

# This is a block comment.
# It spans several lines.
# Each line starts with its own #.
print("only this line actually runs")

Kamu hampir tidak pernah mengetik # itu satu per satu. Setiap editor yang layak punya shortcut "toggle line comment" yang menambah atau menghapus # di setiap baris yang dipilih:

• VS Code: Cmd + / (macOS) atau Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / atau Ctrl + /
• Vim: tergantung plugin-mu; vim-commentary memetakan gcc untuk satu baris dan gc untuk sebuah pilihan.

Pelajari shortcut di editormu sekali saja, dan "mengomentari blok ini untuk mencoba sesuatu" jadi cukup satu tekanan tombol.

Trik string dengan tanda kutip tiga (dan kenapa itu bukan komentar sungguhan)

Kadang kamu akan melihat kode seperti ini:

"""
This block looks like a comment
but it's actually a string literal
that nothing uses.
"""
print("hi")

Secara teknis, itu adalah ekspresi string yang dibuang. Python mem-parse-nya, mengevaluasinya, lalu membuang hasilnya. Ia berperilaku seperti komentar, tapi bukan komentar. Dari sisi gaya, cara ini hanya bagus di satu tempat tertentu: sebagai docstring.

Docstring: satu-satunya tempat yang cocok untuk tanda kutip tiga

Docstring adalah string dengan tanda kutip tiga yang ditaruh sebagai pernyataan paling pertama di sebuah fungsi, class, atau module. Python mengenalinya sebagai dokumentasi dan menyediakannya saat program berjalan lewat fungsi help() dan atribut __doc__:

def discount(price, percent):
    """Return the final price after applying a percentage discount.

    price is a number; percent is between 0 and 100.
    """
    return price * (1 - percent / 100)

print(discount(50, 20))
help(discount)

Dua hal yang membuat docstring bagus:

1. Alat seperti IDE, help(), dan pembuat dokumentasi membacanya secara otomatis. Komentar di atas fungsi tidak mendapat perlakuan seperti itu.
2. Docstring menjelaskan fungsi di tempat ia dipanggil: saat seseorang mengarahkan kursor ke discount(...) di editornya, docstring muncul sebagai tooltip.

Ada konvensi (PEP 257) tentang isi docstring: ringkasan satu baris di baris pertama, satu baris kosong, lalu deskripsi yang lebih panjang kalau perlu. Jangan pusingkan format persisnya di hari pertama: satu baris sederhana tetap jauh lebih baik daripada tidak ada docstring sama sekali.

Apa yang sebenarnya ditulis oleh komentar yang baik

Beberapa pedoman yang akan menghindarkanmu dari banyak sakit kepala nanti:

• Utamakan menjelaskan kenapa, bukan apa. # Loop over the users hanya gangguan; # Retry on 503 - Redis sometimes dies mid-deploy sangat berharga.
• Perbarui komentar saat kamu mengubah kodenya. Komentar yang salah lebih buruk daripada tidak ada komentar. Komentar yang usang justru menyesatkan pembaca berikutnya.
• Jangan mengomentari kode lalu membiarkannya di sana. Kalau tidak dibutuhkan, hapus saja. Version control mengingatnya. File yang penuh blok kode yang dikomentari cepat menjadi tidak bisa dipercaya.
• Lewati hal yang sudah jelas. x = x + 1 # increment x tidak menambah apa-apa.

Intinya

Komentar gratis untuk ditulis dan tidak rugi untuk dilewati. Pakai komentar saat kamu meninggalkan catatan yang akan disyukuri pembacamu: alasan halus kenapa sesuatu berhasil, link ke sebuah issue, peringatan tentang kasus tepi. Pakai docstring saat kamu mendefinisikan fungsi atau class. Selebihnya, biarkan nama yang jelas dan fungsi yang kecil yang berbicara.

Sekarang kamu sudah punya semua yang dibutuhkan untuk membaca dan menulis file Python. Bab berikutnya adalah saat bahasa ini mulai benar-benar melakukan sesuatu: variabel, tipe data, dan nilai yang bisa disimpan Python.