Python - Docstrings (Indonesia)

Halo, para pemrogram Python yang ambisius! Hari ini, kita akan memasuki dunia yang menakjubkan dari docstrings. Sebagai guru ilmu komputer yang ramah di lingkungan Anda, saya sangat senang untuk menemani Anda melalui aspek penting ini dari pemrograman Python. Jadi, ambil minuman kesukaan Anda, bersantailah, dan mari kita mulai petualangan belajar ini bersama-sama!

Docstrings di Python

Bayangkan Anda sedang menulis catatan harian. Pada awal setiap entri, Anda mungkin akan membuat ringkasan singkat tentang apa yang terjadi hari itu. Docstrings di Python mirip seperti itu! Ini adalah string khusus yang menggambarkan apa yang dilakukan oleh potongan kode, membuat itu lebih mudah bagi Anda (dan orang lain) untuk mengerti kode Anda nanti.

Di Python, docstrings diwujudkan dalam tanda kutip triple (""" atau ''') dan ditempatkan tepat setelah definisi dari fungsi, kelas, atau modul. Mari kita lihat contoh sederhana:

def sapa(nama):
"""Fungsi ini menyapa orang yang diberikan sebagai parameter"""
print(f"Halo, {nama}!")

Dalam contoh ini, baris di antara tanda kutip triple adalah docstring kami. Ini menjelaskan singkat apa yang dilakukan oleh fungsi sapa.

Docstrings Satu Baris

Untuk fungsi atau kelas yang sederhana, docstring satu baris mungkin sudah cukup untuk Anda. Ini adalah contoh lain:

def kuadrat(n):
"""Kembalikan kuadrat dari sebuah angka."""
return n ** 2

Docstring ini singkat dan manis, memberitahu kita persis apa yang dilakukan fungsi tersebut hanya dalam satu baris.

Docstrings Multi-Baris

Untuk fungsi atau kelas yang lebih kompleks, Anda mungkin memerlukan docstring multi-baris. Ini biasanya termasuk baris ringkasan, diikuti dengan baris kosong, dan kemudian informasi yang lebih detil. Mari kita lihat contoh:

def hitung_area(panjang, lebar):
"""
Hitung luas persegi panjang.

Parameter:
panjang (float): Panjang persegi panjang
lebar (float): Lebar persegi panjang

Kembali:
float: Luas persegi panjang
"""
return panjang * lebar

Docstring multi-baris ini memberikan informasi yang lebih detil tentang parameter fungsi dan apa yang dikembalikannya.

Docstrings untuk Modul

Modul juga dapat memiliki docstrings! Ini ditempatkan di awal file:

"""
Modul ini berisi fungsi utilitas untuk perhitungan geometri.
Ini termasuk fungsi untuk menghitung luas dan volume berbagai bentuk.
"""

def hitung_luas_lingkaran(jari_jari):
# Implementasi fungsi di sini

Docstrings untuk Kelas

Kelas juga dapat memiliki docstrings. Ini ditempatkan tepat setelah definisi kelas:

class PersegiPanjang:
"""
Kelas untuk mewakili persegi panjang.

Atribut:
panjang (float): Panjang persegi panjang
lebar (float): Lebar persegi panjang
"""

def __init__(self, panjang, lebar):
self.panjang = panjang
self.lebar = lebar

Mengakses Docstrings

Salah satu hal yang keren tentang docstrings adalah Anda dapat mengakses mereka secara program. Python menyimpan docstring sebagai atribut __doc__ dari fungsi, kelas, atau modul. Ini cara Anda mengaksesnya:

def sapa(nama):
"""Fungsi ini menyapa orang yang diberikan sebagai parameter"""
print(f"Halo, {nama}!")

print(sapa.__doc__)

Ini akan menghasilkan: Fungsi ini menyapa orang yang diberikan sebagai parameter

Praktik Terbaik untuk Menulis Docstrings

Sekarang bahwa kita tahu cara menulis docstrings, mari kita berbicara tentang beberapa praktik terbaik:

1. Jaga agar ringkas tetapi informatif
2. Gunakan tata bahasa dan tanda baca yang benar
3. Konsistent dalam gaya Anda
4. Sertakan informasi tentang parameter dan nilai kembalian untuk fungsi
5. Untuk kelas, jelaskan atribut dan metode yang penting

Gaya Docstring Google

Google memiliki panduan gaya untuk docstrings. Ini adalah contoh:

def bagi(a, b):
"""Bagi dua angka.

Args:
a (int): Pembilang.
b (int): Penyebut.

Returns:
float: Hasil dari pembagian.

Raises:
ZeroDivisionError: Jika b adalah 0.
"""
if b == 0:
raise ZeroDivisionError("Tidak dapat membagi dengan nol")
return a / b

Gaya Docstring NumPy/SciPy

Jika Anda bekerja dengan pustaka Python ilmiah, Anda mungkin menemui gaya NumPy/SciPy:

def hitung_rerata(nomor):
"""
Hitung rerata aritmatika dari daftar angka.

Parameters
----------
nomor : list
Daftar angka.

Returns
-------
float
Rerata aritmatika dari daftar input.
"""
return sum(nomor) / len(nomor)

Gaya Docstring Sphinx

Sphinx adalah generator dokumentasi populer untuk Python. Gaya itu mirip dengan format reStructuredText:

def fibonacci(n):
"""
Buat urutan Fibonacci hingga n.

:param n: Jumlah bilangan Fibonacci yang akan dibuat
:type n: int
:return: Daftar bilangan Fibonacci
:rtype: list
"""
urutan = [0, 1]
while len(urutan) < n:
urutan.append(urutan[-1] + urutan[-2])
return urutan[:n]

Docstring vs Komentar

Anda mungkin bertanya-tanya, "Apa bedanya antara docstring dan komentar biasa?" Pertanyaan yang bagus! Mari kita pecahkan:

1. Sintaks: Docstrings menggunakan tanda kutip triple, sementara komentar menggunakan #.
2. Penempatan: Docstrings datang setelah definisi, sementara komentar dapat ditempatkan di mana saja.
3. Tujuan: Docstrings menjelaskan apa yang dilakukan kode, komentar menjelaskan bagaimana itu dilakukan.
4. Aksesibilitas: Docstrings dapat diakses secara program, sedangkan komentar tidak.

Ini adalah contoh cepat untuk mengilustrasikannya:

def tambah(a, b):
"""
Tambahkan dua angka dan kembalikan hasilnya.
"""
# Ini adalah komentar menjelaskan bagaimana kita melakukan penambahan
return a + b  # Ini adalah komentar inline

Dan itu sudah semua, teman-teman! Kita telah membahas mengenai docstrings Python dari segala sisi. Ingat, dokumentasi yang baik adalah seperti meninggalkan jejak kue kering untuk masa depan Anda (atau pengembang lain) untuk mengikuti. Mungkin itu tampak seperti pekerjaan tambahan sekarang, tetapi percayalah, Anda akan berterima kasih kepada diri Anda nanti!

Berikut adalah tabel referensi cepat dari gaya docstring yang kita telah membahas:

Style	Summary	Example
Single-Line	Deskripsi singkat satu baris	"""Kembalikan kuadrat dari sebuah angka."""
Multi-Line	Deskripsi detil dengan parameter dan nilai kembalian	"""Hitung luas persegi panjang.\n\nParameter:\n..."""
Google	Termasuk Args, Returns, dan Raises seksi	"""Bagi dua angka.\n\nArgs:\n..."""
NumPy/SciPy	Menggunakan Parameters dan Returns seksi dengan format yang lebih detil	"""Hitung rerata aritmatika dari daftar angka.\n\nParameters\n----------\n..."""
Sphinx	Menggunakan :param:, :type:, :return:, dan :rtype: bidang	"""Buat urutan Fibonacci hingga n.\n\n:param n: ..."""

Selamat coding, dan semoga docstrings Anda selalu jelas dan informatif!

Credits: Image by storyset