Kode yang baik menyertakan komentar untuk membantu memahaminya, dan dokumen dapat memainkan peran utama dalam hal itu.

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. Potongan kode tersebut dapat berupa a 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.

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.

instagram viewer

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.

defberkembang biak(a, b):
Mengalikan dua angka dan mengembalikan hasilnya
kembali a * b

Gunakan docstring multi-baris untuk kode yang lebih kompleks yang memerlukan dokumentasi mendetail.

Pertimbangkan kelas Mobil berikut:

kelasMobil:

 A kelasmewakiliAmobilobyek.
 Atribut:
 jarak tempuh (float): Jarak tempuh mobil saat ini.


 Metode:
 drive (miles): Mengendarai mobil untuk jumlah mil yang ditentukan.


def__init__(diri sendiri, jarak tempuh):
 self.mileage = jarak tempuh


defmenyetir(diri sendiri, mil):

 Mengendarai mobil untuk jumlah mil yang ditentukan.


 argumen:
 miles (float): Jumlah mil yang harus dikendarai.
 Pengembalian:
Tidak ada

 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—docstrings 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 dengan cepat memahami tujuannya tanpa melalui seluruh kode memblokir.

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:

defberkembang biak(a, b):

 Kalikan dua angka sekaligus.
 @param a: Angka pertama yang akan dikalikan.
 @ketik a: int
 @param b: Angka kedua yang akan dikalikan.
 @tipe b: int
 @return: Produk dari dua angka.
 @tipe: int

kembali a * b

reStructuredText (REST)

Sebuah docstring yang mengikuti format reST:

defberkembang biak(a, b):

 Kalikan dua angka sekaligus.
 :param a: Angka pertama yang dikalikan.
: ketik a: int
 :param b: Angka kedua yang akan dikalikan.
: tipe b: int
 :kembali: Produk dari dua angka.
 :rtype: int

kembali a * b

NumPy

Sebuah docstring yang mengikuti format NumPy:

defberkembang biak(a, b):

 Kalikan dua angka sekaligus.
 Parameter

 a: int
 Angka pertama yang dikalikan.
 b: int
 Angka kedua untuk dikalikan.
 Pengembalian

 int
 Produk dari dua angka.

kembali a * b

Google

Sebuah docstring yang mengikuti format Google:

defberkembang biak(a, b):

 Kalikan dua angka sekaligus.
 argumen:
 a (int): Angka pertama yang akan dikalikan.
 b (int): Angka kedua yang akan dikalikan.
 Pengembalian:
 int: Produk dari dua angka.

kembali 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:

defberkembang biak(a, b):

 Kalikan dua angka sekaligus.
 Parameter

 a: int
 Angka pertama yang dikalikan.
 b: int
 Angka kedua untuk dikalikan.


 Pengembalian

 int
 Produk dari dua angka.
 Contoh

 >>> kalikan(2, 3)
6
 >>> kalikan(0, 10)
0
 >>> kalikan(-1, 5)
-5

kembali 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 doctests bukan pengganti yang lebih komprehensif pengujian unit dan pengujian integrasi 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.