Python - Docstrings

Helo, pemrogram Python yang berhasrat! Hari ini, kita akan menyelam ke atas dunia yang menakjubkan docstrings. Sebagai guru sains komputer yang ramah di sekitar anda, saya sangat gembira untuk memandu anda melalui aspek penting ini dari pemrograman Python. Jadi, ambil minuman kesukaan anda, bersantai, dan mari kita mulai perjalanan pembelajaran ini bersama-sama!

Docstrings di Python

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

Di Python, docstrings diwakili oleh tanda kutip triple (""" atau ''') dan diletakkan tepat setelah definisi fungsi, kelas, atau modul. Mari kita lihat contoh sederhana:

def greet(name):
"""Fungsi ini untuk menyapa orang yang diberikan sebagai parameter"""
print(f"Helo, {name}!")

Dalam contoh ini, baris di antara tanda kutip triple adalah docstring kita. Ia menjelaskan singkat apa yang dilakukan oleh fungsi greet.

Docstrings Baris Tunggal

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

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

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

Docstrings Banyak Baris

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

def calculate_area(length, width):
"""
Menghitung luas persegi panjang.

Parameter:
length (float): Panjang persegi panjang
width (float): Lebar persegi panjang

Kembali:
float: Luas persegi panjang
"""
return length * width

Docstring banyak baris ini menyediakan informasi yang lebih detil tentang parameter fungsi dan apa yang dikembalikannya.

Docstrings untuk Modul

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

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

def calculate_circle_area(radius):
# Implementasi fungsi di sini

Docstrings untuk Kelas

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

class Rectangle:
"""
Kelas ini mewakili persegi panjang.

Atribut:
length (float): Panjang persegi panjang
width (float): Lebar persegi panjang
"""

def __init__(self, length, width):
self.length = length
self.width = width

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 adalah bagaimana anda dapat mengaksesnya:

def greet(name):
"""Fungsi ini untuk menyapa orang yang diberikan sebagai parameter"""
print(f"Helo, {name}!")

print(greet.__doc__)

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

Praktek Terbaik untuk Menulis Docstrings

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

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

Gaya Docstring Google

Google memiliki panduan gaya sendiri untuk docstrings. Ini adalah contoh:

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

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

Returns:
float: Hasil pembagian.

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

Gaya Docstring NumPy/SciPy

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

def calculate_mean(numbers):
"""
Menghitung rata-rata aritmatika dari daftar angka.

Parameters
----------
numbers : list
Daftar angka.

Returns
-------
float
Rata-rata aritmatika dari daftar input.
"""
return sum(numbers) / len(numbers)

Gaya Docstring Sphinx

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

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

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

Docstring vs Komentar

Anda mungkin bertanya-tanya, "Apa perbedaan antara docstring dan komentar reguler?" 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 diletakkan 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 add(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 adalah, folks! Kita telah membahas mengenai docstrings Python. Ingat, dokumentasi yang baik adalah seperti meninggalkan jejak roti untuk masa depan anda (atau pengembang lain) untuk mengikuti. Mungkin saja terasa seperti kerja tambahan sekarang, tapi percayalah, anda akan berterima kasih kepada diri sendiri nanti!

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

Style	Ringkasan	Contoh
Baris Tunggal	Deskripsi singkat satu baris	"""Kembalikan kuasa dari sebuah angka."""
Banyak Baris	Deskripsi detil dengan parameter dan nilai kembali	"""Menghitung 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	"""Menghitung rata-rata aritmatika dari daftar angka.\n\nParameters\n----------\n..."""
Sphinx	Menggunakan :param:, :type:, :return:, dan :rtype: bidang	"""Menghasilkan urutan Fibonacci hingga n.\n\n:param n: ..."""

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

Credits: Image by storyset