Komentar, docstring, dan PEP 8

Kode dibaca jauh lebih sering daripada ditulis, sehingga keterbacaan menyertai kebenaran sebagai tujuan penulisan program. Python menyediakan dua sarana penjelasan di dalam kode, yaitu komentar untuk pembaca kode dan docstring untuk dokumentasi yang tersimpan pada program itu sendiri, sedangkan PEP 8 mengatur gaya penulisannya mulai dari penamaan hingga spasi. Topik ini membahas ketiganya secara berurutan, disertai contoh yang memperlihatkan bagian mana yang diabaikan interpreter dan bagian mana yang memengaruhi jalannya program.

Komentar dengan tanda pagar#

Komentar diawali tanda pagar #, dan interpreter mengabaikan seluruh teks setelah tanda itu sampai akhir baris. Komentar boleh menempati satu baris penuh atau menyambung di akhir baris kode. Karena sepenuhnya diabaikan, komentar tidak memengaruhi hasil eksekusi sedikit pun, dan penghapusan seluruh komentar pada suatu berkas tidak mengubah keluarannya.

# menghitung jumlah kata pada satu kalimat
kalimat = "satu dua tiga empat"   # data yang dianalisis
jumlah = len(kalimat.split())     # split() memisah per kata
print("Jumlah kata:", jumlah)

Jumlah kata: 4

Keluaran di atas dihasilkan tanpa memedulikan tiga komentar yang mengiringi kodenya. Komentar yang berguna menjelaskan hal yang tidak terlihat dari kode itu sendiri, misalnya alasan sebuah pilihan, peringatan tentang perilaku khusus, atau rujukan spesifikasi. Sebaliknya, komentar yang sekadar mengulang isi barisnya hanya menambah kebisingan, dan komentar yang tidak diperbarui saat kode berubah lebih menyesatkan daripada tidak ada komentar sama sekali. Kaidah praktisnya, tulis komentar untuk menjawab mengapa, dan biarkan kode menjawab apa.

Docstring untuk dokumentasi#

Docstring adalah string literal yang ditulis sebagai pernyataan pertama di dalam sebuah fungsi, kelas, atau modul. Berbeda dengan komentar, docstring tersimpan pada objeknya melalui atribut __doc__, sehingga dapat dibaca saat program berjalan. Contoh berikut menampilkan nilai kembali sebuah fungsi, isi docstringnya melalui __doc__, lalu ringkasan yang dirakit fungsi help().

def luas_persegi(sisi):
    """Menghitung luas persegi dari panjang sisinya."""
    return sisi * sisi

print(luas_persegi(6))
print(luas_persegi.__doc__)
help(luas_persegi)

36
Menghitung luas persegi dari panjang sisinya.
Help on function luas_persegi in module __main__:

luas_persegi(sisi)
    Menghitung luas persegi dari panjang sisinya.

Pernyataan def membentuk fungsi bernama luas_persegi, dan string tiga kutip ganda tepat setelahnya menjadi docstringnya. Atribut __doc__ menyimpan teks itu apa adanya, sedangkan help() merangkumnya bersama nama parameter menjadi tampilan yang siap dibaca. PEP 257 menetapkan konvensi penulisannya, di antaranya docstring dibungkus tiga tanda kutip ganda dan baris pertamanya merupakan ringkasan singkat dalam kalimat lengkap.

Komentar dan docstring mempunyai pembagian tugas yang jelas. Komentar ditujukan kepada orang yang membaca kode sumbernya baris demi baris, sedangkan docstring ditujukan kepada pengguna objek yang memeriksanya melalui help() atau alat dokumentasi otomatis. Menyimpan penjelasan pada tempat yang tepat membuat keduanya tetap berguna tanpa saling menggantikan.

Konvensi gaya PEP 8#

PEP 8 adalah panduan gaya resmi (style guide) untuk kode Python, diterbitkan sebagai bagian dari Python Enhancement Proposal, yaitu rangkaian dokumen standar ekosistem Python. Isinya mencakup penamaan, spasi, tata letak, panjang baris, hingga urutan impor. PEP 8 bukan aturan kebenaran, karena interpreter menerima kode dengan gaya apa pun selama sintaksnya sah dan pelanggaran gaya tidak pernah memicu error. Tujuannya adalah keseragaman, yaitu kode dari proyek yang berbeda terbaca dengan pola yang sama.

Penegakan gaya umumnya diserahkan kepada alat pemeriksa (linter) dan alat pemformat otomatis yang membandingkan kode dengan aturan PEP 8, sehingga aturannya dapat diterapkan tanpa menghafal setiap butirnya. Tiga kelompok aturan yang paling sering ditemui pemula adalah penamaan, spasi, dan tata letak, dan ketiganya dibahas pada bagian-bagian berikut.

Penamaan sesuai PEP 8#

PEP 8 menetapkan gaya penamaan berbeda untuk setiap jenis unsur kode, sehingga peran sebuah nama terbaca sekilas tanpa membaca konteksnya. Tabel berikut merangkum gaya yang paling sering dipakai.

suhu_rata_rata = 27.5
BATAS_MAKSIMUM = 40

def hitung_selisih(a, b):
    return a - b

print(hitung_selisih(BATAS_MAKSIMUM, suhu_rata_rata))

12.5

Huruf besar pada BATAS_MAKSIMUM adalah penanda konvensi, bukan penjaga nilai, karena Python tetap mengizinkan penugasan ulang atas namanya. Penanda semacam itu membantu pembaca mengenali nilai yang seharusnya tidak diubah selama program berjalan. Gaya snake_case menjadi pilihan baku untuk variabel dan fungsi di seluruh kode Python, sehingga kebiasaan menuliskannya sejak program kecil akan terbawa pada proyek yang lebih besar.

Spasi dan tata letak#

Aturan spasi PEP 8 yang paling sering dipakai meliputi empat hal. Indentasi menggunakan empat spasi untuk setiap tingkat. Satu spasi diberikan di sekitar operator dan setelah setiap koma.

Spasi tidak diberikan langsung sebelum tanda kurung pemanggilan fungsi. Definisi fungsi tingkat atas dipisahkan dua baris kosong. Untuk tata letak, panjang baris dianjurkan tidak melebihi 79 karakter.

total=17+25
print(total)

total = 17 + 25
print(total)

42
42

Kedua versi penugasan di atas menghasilkan nilai yang sama, karena spasi di sekitar operator menyangkut keterbacaan, bukan semantik. Hal itu tidak berlaku untuk indentasi. Indentasi menentukan struktur blok pada Python, sehingga jumlah spasi yang tak konsisten mengubah makna program atau langsung memicu error sintaks. PEP 8 menetapkan empat spasi agar seluruh kode Python tampak seragam, dan tanda tab tidak boleh dicampur dengan spasi pada satu berkas.

Kesalahan umum#

Kesalahan pertama adalah menulis string yang dimaksudkan sebagai docstring pada posisi yang bukan pernyataan pertama. Python hanya menyimpan docstring dari pernyataan pertama, sedangkan string literal pada posisi lain dihitung sebagai ekspresi biasa lalu dibuang.

def sapa():
    print("menyiapkan sapaan")
    "Selamat pagi."      # bukan docstring karena bukan pernyataan pertama
    return "Selamat pagi."

print(sapa())
print(sapa.__doc__)

menyiapkan sapaan
Selamat pagi.
None

Fungsi tetap berjalan dan mengembalikan salamnya, tetapi atribut __doc__ bernilai None karena string itu ditulis setelah pernyataan print(). Perbaikannya adalah memindahkan string tiga kutip ke posisi pertama di dalam badan fungsi.

Kesalahan kedua adalah menggunakan jumlah spasi indentasi yang tidak konsisten. Struktur blok Python ditentukan oleh indentasi, sehingga baris yang tidak sejajar dengan tingkatnya memicu error sintaks berjenis IndentationError.

# tidak-dijalankan: jumlah spasi indentasi yang tak konsisten memicu error sintaks
def status(skor):
    if skor >= 75:
        return "lulus"
      return "belum"

Pesan IndentationError menunjuk baris yang tidak sejajar, dan perbaikannya adalah menyamakan jumlah spasi setiap tingkat pada satu berkas. Kebiasaan memakai empat spasi sejak awal mencegah error semacam ini.

Kesalahan ketiga adalah memakai komentar untuk menutupi nama yang buruk, misalnya baris r = j / n yang dijelaskan dengan komentar bahwa r adalah rata-rata. Komentar semacam itu harus dibaca setiap kali nama r muncul, sedangkan nama rata_rata menjelaskan dirinya sendiri tanpa komentar apa pun. Apabila sebuah komentar hanya menjawab pertanyaan apa, pertimbangkan mengganti nama unsur kodenya alih-alih mempertahankan komentarnya.

Ringkasan#

• Komentar diawali tanda # dan diabaikan interpreter sepenuhnya, sedangkan docstring tersimpan pada atribut __doc__ dan dapat dibaca melalui help().
• Docstring hanya tersimpan apabila ditulis sebagai pernyataan pertama fungsi, kelas, atau modul.
• PEP 8 menetapkan snake_case untuk variabel dan fungsi, huruf besar untuk konstanta, dan CapWords untuk kelas.
• Spasi di sekitar operator hanya menyangkut keterbacaan, sedangkan indentasi menentukan struktur blok dan wajib konsisten dengan empat spasi per tingkat.

Referensi#

• PEP 8: Style Guide for Python Code — Python Software Foundation — Panduan gaya resmi Python untuk penamaan, spasi, tata letak, dan panjang baris.
• PEP 257: Docstring Conventions — Python Software Foundation — Konvensi resmi penulisan docstring beserta contoh yang dianjurkan.
• Documentation Strings — Python Software Foundation — Bagian tutorial resmi tentang docstring dan hubungannya dengan help().