Docstring — Menjelaskan Fungsimu

Aturan resmi Python soal menulis penjelasan fungsi. Isinya pendek, dan kebiasaan ini layak dibentuk sejak fungsi pertamamu.

Bentuknya

def luas_lingkaran(jari):
    """Hitung luas lingkaran dari jari-jarinya."""
    return 3.14159 * jari ** 2

Baris berkutip tiga itu harus jadi pernyataan pertama di dalam fungsi — sebelum kode apa pun.

Kenapa layak ditulis

>>> help(luas_lingkaran)
luas_lingkaran(jari)
    Hitung luas lingkaran dari jari-jarinya.

Selain itu, VS Code menampilkannya sebagai tooltip setiap kali kamu mengetik nama fungsi itu di tempat lain. Kamu tidak perlu membuka file aslinya untuk mengingat cara pakainya — dan tiga bulan lagi, “orang lain” yang terbantu itu adalah kamu sendiri.

Gaya penulisan

# Baik — kalimat perintah, langsung ke inti
def kena_pajak(harga):
    """Hitung nilai PPN 11% dari sebuah harga."""

# Kurang baik — bertele-tele tanpa menambah informasi
def kena_pajak(harga):
    """Fungsi ini adalah fungsi yang digunakan untuk menghitung pajak."""

# Tidak berguna — hanya mengulang nama fungsinya
def kena_pajak(harga):
    """Kena pajak."""

Docstring beberapa baris

def hitung_gaji(pokok, lembur_jam=0, potongan_persen=5):
    """Hitung gaji bersih bulanan.

    Lembur dibayar Rp 25.000 per jam dan tidak kena potongan.
    Potongan dihitung dari gaji pokok saja.
    Semua nilai dalam rupiah, dikembalikan sebagai float.
    """
    lembur = lembur_jam * 25000
    potongan = pokok * potongan_persen / 100
    return pokok - potongan + lembur

Susunannya: satu kalimat ringkas, baris kosong, lalu detail. Kutip penutupnya ditaruh di barisnya sendiri.

Docstring versus komentar

def bagi_aman(a, b):
    """Bagi a dengan b; kembalikan None kalau b nol."""
    if b == 0:
        # Sengaja tidak melempar error: pemanggil di laporan bulanan
        # lebih suka baris kosong daripada program berhenti.
        return None
    return a / b

Komentar yang tidak perlu

# Buruk — mengulang apa yang sudah jelas terbaca
i = i + 1        # tambah i dengan 1

# Baik — menjelaskan sesuatu yang tidak terlihat dari kodenya
i = i + 1        # lewati baris header di file CSV