Cara Mendokumentasikan Kode Python Menggunakan Docstrings
Table of content:
Tanpa dokumentasi yang tepat, akan sulit untuk memahami, memelihara, dan men-debug kode Anda. Di Python, Anda bisa menggunakan docstrings untuk memberikan deskripsi singkat dan contoh cara kerja kode.
Apakah Docstring itu?
Docstring adalah string yang dapat Anda tambahkan ke kode Python Anda untuk menjelaskan fungsinya dan cara menggunakannya. Sepotong kode bisa berupa fungsi Python, modul, atau kelas.
Docstrings sangat mirip dengan komentar Python standar, tetapi memiliki beberapa perbedaan. Komentar Python memberikan informasi tambahan kepada pengembang tentang cara kerja kode, seperti detail implementasi atau peringatan yang perlu diingat saat memperluas kode.
Baca Juga:
Di sisi lain, sebagian besar docstring memberikan informasi kepada pengguna kode yang mungkin tidak perlu mengetahui detail implementasinya tetapi perlu memahami apa fungsinya dan bagaimana menggunakannya.
Cara Menulis Docstrings
Anda biasanya menyertakan docstring di awal blok kode yang ingin Anda dokumentasikan. Anda harus mengapitnya dengan tanda kutip tiga (“””). Anda dapat menulis dokumen satu baris atau dokumen multi baris.
Docstring satu baris cocok untuk kode sederhana yang tidak memerlukan banyak dokumentasi.
Di bawah ini adalah contoh fungsi yang disebut perkalian. Docstring menjelaskan fungsi perkalian mengambil dua angka, mengalikannya, dan mengembalikan hasilnya.
def multiply(a, b):
"""Multiplies two numbers and returns the result"""
return a * b
Gunakan docstring multi-baris untuk kode yang lebih kompleks yang memerlukan dokumentasi mendetail.
Pertimbangkan kelas Mobil berikut:
class Car:
"""
A class representing a car object. Attributes:
mileage (float): The current mileage of the car.
Methods:
drive(miles): Drives the car for the specified number of miles.
"""
def __init__(self, mileage):
self.mileage = mileage
def drive(self, miles):
"""
Drives the car for the specified number of miles.
Args:
miles (float): The number of miles to drive.
Returns:
None
"""
self.mileage += miles
Docstring untuk kelas di atas menjelaskan apa yang diwakili oleh kelas, atributnya, dan metodenya. Sementara itu, docstring untuk metode drive memberikan informasi tentang apa yang dilakukan metode, argumen yang diharapkan, dan apa yang dikembalikan.
Ini memudahkan siapa saja yang bekerja dengan kelas ini untuk memahami cara menggunakannya. Manfaat lain menggunakan docstring meliputi:
- Pemeliharaan kode: Dengan memberikan deskripsi yang jelas tentang cara kerja kode, docstrings membantu pengembang memodifikasi dan memperbarui kode tanpa menimbulkan kesalahan.
- Kolaborasi yang lebih mudah: Ketika beberapa pengembang berkolaborasi pada basis kode yang sama—misalnya, dengan alat berbagi langsung Visual Studio—docstring memungkinkan pengembang untuk mendokumentasikan kode secara konsisten sehingga semua orang dalam tim dapat memahaminya.
- Keterbacaan kode yang ditingkatkan: Docstrings memberikan ringkasan tingkat tinggi tentang apa yang dilakukan kode yang memungkinkan siapa pun yang membaca kode untuk memahami tujuannya dengan cepat tanpa melalui seluruh blok kode.
Format Docstring
Docstring yang baik harus menjelaskan apa yang dilakukan oleh sebuah kode, argumen yang diharapkan, dan detail implementasi jika diperlukan. Ini terutama harus mencakup setiap kasus tepi yang harus diketahui oleh siapa pun yang menggunakan kode tersebut.
Format docstring dasar memiliki bagian berikut:
- Baris ringkasan: Ringkasan satu baris tentang apa yang dilakukan kode.
- Argumen: Informasi tentang argumen yang diharapkan fungsi termasuk tipe datanya.
- Nilai pengembalian: Informasi tentang nilai pengembalian fungsi termasuk tipe datanya.
- Kenaikan (opsional): Informasi tentang pengecualian apa pun yang mungkin ditimbulkan oleh fungsi.
Ini hanyalah format dasar karena ada format lain yang dapat Anda pilih untuk mendasarkan dokumen Anda. Yang paling populer adalah Epytext, reStructuredText (juga dikenal sebagai reST), NumPy, dan dokumen Google. Masing-masing format ini memiliki sintaksnya sendiri seperti yang ditunjukkan pada contoh berikut:
Epiteks
Sebuah docstring yang mengikuti format Epytext:
def multiply(a, b):
"""
Multiply two numbers together. @param a: The first number to multiply.
@type a: int
@param b: The second number to multiply.
@type b: int
@return: The product of the two numbers.
@rtype: int
"""
return a * b
reStructuredText (REST)
Sebuah docstring yang mengikuti format reST:
def multiply(a, b):
"""
Multiply two numbers together. :param a: The first number to multiply.
:type a: int
:param b: The second number to multiply.
:type b: int
:return: The product of the two numbers.
:rtype: int
"""
return a * b
NumPy
Sebuah docstring yang mengikuti format NumPy:
def multiply(a, b):
"""
Multiply two numbers together. Parameters
----------
a : int
The first number to multiply.
b : int
The second number to multiply.
Returns
-------
int
The product of the two numbers.
"""
return a * b
Sebuah docstring yang mengikuti format Google:
def multiply(a, b):
"""
Multiply two numbers together. Args:
a (int): The first number to multiply.
b (int): The second number to multiply.
Returns:
int: The product of the two numbers.
"""
return a * b
Meskipun keempat format docstring menyediakan dokumentasi yang berguna untuk fungsi perkalian, format NumPy dan Google lebih mudah dibaca daripada format Epytext dan reST.
Cara Menyertakan Tes di Docstrings
Anda dapat menyertakan contoh pengujian dalam dokumen Anda menggunakan modul doctest. Modul doctest mencari docstring untuk teks yang terlihat seperti sesi Python interaktif dan kemudian mengeksekusinya untuk memverifikasi bahwa mereka berfungsi sebagaimana mestinya.
Untuk menggunakan doctests, sertakan input sampel dan output yang diharapkan dalam docstring. Di bawah ini adalah contoh bagaimana Anda akan melakukannya:
def multiply(a, b):
"""
Multiply two numbers together. Parameters
----------
a : int
The first number to multiply.
b : int
The second number to multiply.
Returns
-------
int
The product of the two numbers.
Examples
--------
>>> multiply(2, 3)
6
>>> multiply(0, 10)
0
>>> multiply(-1, 5)
-5
"""
return a * b
Itu Contoh bagian berisi tiga panggilan fungsi dengan argumen yang berbeda dan menentukan output yang diharapkan untuk masing-masing. Ketika Anda menjalankan modul doctest seperti yang ditunjukkan di bawah ini, itu akan mengeksekusi contoh dan membandingkan keluaran aktual dengan keluaran yang diharapkan.
python -m doctest multiply.py
Jika ada perbedaan, modul doctest melaporkannya sebagai kegagalan. Menggunakan doctests dengan docstrings seperti ini membantu Anda memverifikasi bahwa kode berfungsi seperti yang diharapkan. Perhatikan bahwa doctest bukanlah pengganti untuk pengujian unit dan pengujian integrasi yang lebih komprehensif untuk kode Python Anda.
Bagaimana Menghasilkan Dokumentasi Dari Docstrings
Anda telah mempelajari dasar-dasar penggunaan docstring untuk mendokumentasikan kode Python Anda dan pentingnya dokumentasi berkualitas tinggi. Untuk meningkatkannya, Anda mungkin ingin membuat dokumentasi untuk modul dan fungsi Anda dari dokumen masing-masing.
Salah satu generator dokumentasi paling populer yang dapat Anda gunakan adalah Sphinx. Ini mendukung format docstring rest secara default tetapi Anda dapat mengonfigurasinya agar berfungsi dengan format Google atau NumPy.
Artikel Terkait
