Komentar dan Docstring

Kode ditulis sekali, tetapi dibaca berkali-kali — oleh rekan tim, dan sering kali oleh penulisnya sendiri beberapa bulan kemudian. Python menyediakan dua mekanisme untuk menjelaskan kode kepada manusia: komentar, yaitu catatan di dalam kode yang sepenuhnya diabaikan interpreter, dan docstring, yaitu dokumentasi resmi yang menempel pada module, function, atau class dan dapat diakses program lain. Chapter ini membahas keduanya beserta cara mengakses docstring lewat atribut __doc__ dan function help().

Komentar dengan Tanda Pagar #

Komentar diawali tanda pagar (#) dan berlaku sampai akhir baris. Interpreter tidak pernah mengeksekusi isi komentar — tugas komentar murni untuk manusia. Program berikut memakai komentar satu baris penuh dan komentar ujung baris sekaligus:

"""Program kasir sederhana untuk toko buah."""

harga_apel = 15000    # harga per kilogram
jumlah_beli = 3

# hitung total yang harus dibayar
total = harga_apel * jumlah_beli

print("Total belanja:", total)

Output yang Dihasilkan:

Total belanja: 45000

Mari kita bedah penempatannya:

1. Baris 1 ("""Program kasir ..."""): docstring module — dibedah di bagian berikutnya.
2. Baris 3 (# harga per kilogram): komentar ujung baris, menjelaskan satu data pada baris yang sama. Beri jarak yang cukup agar kode dan komentar tidak menempel.
3. Baris 6 (# hitung total ...): komentar satu baris penuh, menjelaskan maksud blok kode di bawahnya.

Komentar yang baik menjelaskan mengapa, bukan apa. Baris total = harga_apel * jumlah_beli sudah menjelaskan dirinya sendiri; komentar diperlukan justru untuk hal yang tidak terlihat, misalnya # harga mengikuti daftar reseller, bukan harga eceran.

Docstring: Dokumentasi yang Menempel pada Kode #

Docstring adalah string literal yang ditulis sebagai statement pertama sebuah module, function, atau class. Berbeda dari komentar, docstring disimpan oleh Python di atribut __doc__ dan bisa dibaca siapa pun tanpa membuka isi kode. Untuk function, docstring ditulis tepat di bawah baris def:

def hitung_diskon(harga, persen):
    """Menghitung harga setelah dipotong diskon."""
    return harga - (harga * persen / 100)


print(hitung_diskon(100000, 20))
print(hitung_diskon.__doc__)

Output yang Dihasilkan:

80000.0
Menghitung harga setelah dipotong diskon.

Pemanggilan hitung_diskon(100000, 20) menghasilkan 80000.0 — tipe float karena operasi pembagian terlibat dalam perhitungan. Baris kedua membaca atribut __doc__ milik function tersebut, dan isinya persis string yang kita tulis di dalam kode.

Docstring juga boleh terdiri dari beberapa baris untuk penjelasan yang lebih kaya — cukup tulis beberapa paragraf di antara tanda kutip tiga:

def hitung_diskon(harga, persen):
    """Menghitung harga setelah dipotong diskon.

    Menerima harga awal dan persentase diskon,
    lalu mengembalikan harga akhir.
    """
    return harga - (harga * persen / 100)


help(hitung_diskon)

Output yang Dihasilkan:

Help on function hitung_diskon in module __main__:

hitung_diskon(harga, persen)
    Menghitung harga setelah dipotong diskon.

    Menerima harga awal dan persentase diskon,
    lalu mengembalikan harga akhir.

Function help() membaca docstring, lalu menampilkannya bersama signature function — nama function beserta parameternya. Format bantuan ini bekerja untuk semua objek Python yang didokumentasikan dengan docstring, termasuk function bawaan seperti len atau print.

Kapan Menulis Komentar dan Docstring #

Dua mekanisme ini punya wilayah kerja yang berbeda:

Aturan praktis yang lazim: setiap function dan module publik berhak mendapat docstring, sementara komentar dipakai untuk keputusan implementasi yang tidak terlihat dari namanya.

Selain menjelaskan kode, kita juga perlu memahami dua jenis unit penyusunnya. Chapter berikutnya membedakan statement sebagai instruksi lengkap dan expression sebagai kode yang menghasilkan nilai.