Panduan Lengkap Python Docstring: Cara Menulis, Gaya, dan Contoh Praktis

1. Apa itu docstring di Python?

docstring dalam Python adalah string khusus yang digunakan untuk menambahkan deskripsi pada fungsi, kelas, atau modul. docstring sangat penting karena meningkatkan keterbacaan serta pemeliharaan kode, dan memudahkan pengembang lain untuk memahami fungsionalitasnya. Selain itu, dengan menggunakan alat pembuat dokumentasi otomatis (misalnya: Sphinx), docstring dapat dimanfaatkan untuk menghasilkan dokumentasi yang rapi.

Posisi dan Format docstring

docstring ditempatkan tepat setelah definisi fungsi, kelas, atau modul, dan biasanya ditulis dengan tiga tanda kutip ganda. Contoh sintaks umumnya seperti berikut:

def nama_fungsi(argumen):
    """
    Tulis deskripsi singkat fungsi di sini.

    Argumen:
        nama_argumen (tipe): Penjelasan detail tentang argumen
    Return:
        tipe: Penjelasan tentang nilai kembalian
    """
    pass

docstring digunakan oleh fungsi bawaan Python help() maupun fitur bantuan di editor, sehingga memainkan peran penting sebagai dokumentasi kode.

2. Cara Dasar Menulis docstring

docstring pada Python digunakan untuk menjelaskan spesifikasi fungsi atau kelas secara ringkas dan jelas. Format umumnya dimulai dengan tujuan fungsi, lalu diikuti penjelasan tentang parameter, nilai kembali, atau error yang mungkin muncul. Dengan mengikuti panduan resmi PEP 257, kode menjadi konsisten dan lebih mudah dipahami oleh pengembang lain.

Struktur Dasar docstring

docstring satu baris digunakan untuk memberikan deskripsi singkat. Biasanya dipakai untuk menjelaskan fungsi hanya dalam satu kalimat, contohnya:

def add(a, b):
    """Mengembalikan hasil penjumlahan dua angka."""
    return a + b

Untuk penjelasan lebih detail, digunakan docstring multi-baris. Hal ini memuat deskripsi fungsi, parameter, serta nilai kembali dengan struktur yang lebih jelas:

def add(a, b):
    """
    Menjumlahkan dua angka dan mengembalikan hasilnya.

    Argumen:
        a (int): Angka pertama
        b (int): Angka kedua

    Return:
        int: Hasil penjumlahan
    """
    return a + b

3. Gaya docstring (Google Style, NumPy Style, reStructuredText Style)

Berbagai gaya docstring digunakan sesuai proyek atau alat yang dipakai. Tiga gaya yang paling populer adalah Google Style, NumPy Style, dan reStructuredText Style.

Google Style

Google Style menekankan penulisan yang ringkas dan mudah dibaca. Parameter dan nilai kembali ditulis di bawah bagian Args dan Returns, sehingga fungsi Python dapat dipahami dengan cepat.

def add(a, b):
    """
    Menjumlahkan dua angka.

    Args:
        a (int): Angka pertama
        b (int): Angka kedua

    Returns:
        int: Hasil penjumlahan
    """
    return a + b

NumPy Style

NumPy Style menyediakan format lebih detail, sangat umum dipakai dalam dokumentasi pustaka sains dan analisis data. Bagian Parameters dan Returns digunakan untuk penjelasan rinci.

def add(a, b):
    """
    Menjumlahkan dua angka.

    Parameters
    ----------
    a : int
        Angka pertama
    b : int
        Angka kedua

    Returns
    -------
    int
        Hasil penjumlahan
    """
    return a + b

reStructuredText Style

reStructuredText Style digunakan oleh alat pembuat dokumentasi Sphinx, sering dipakai dalam proyek besar. Dengan gaya ini, Sphinx bisa menghasilkan dokumentasi HTML atau PDF secara otomatis.

def add(a, b):
    """
    Menjumlahkan dua angka.

    :param a: Angka pertama
    :type a: int
    :param b: Angka kedua
    :type b: int
    :return: Hasil penjumlahan
    :rtype: int
    """
    return a + b

4. PEP 257 dan Best Practice

PEP 257 adalah panduan resmi gaya penulisan docstring di Python. Dengan mengikutinya, keterbacaan kode meningkat dan lebih mudah dipahami baik oleh pengembang lain maupun diri sendiri.

Poin Penting dari PEP 257

1. docstring satu baris → Untuk fungsi sederhana, gunakan satu baris penjelasan ringkas.
2. docstring multi-baris → Untuk deskripsi detail, baris pertama berisi ringkasan singkat, lalu kosong satu baris, baru lanjutkan dengan penjelasan lengkap.
3. Indentasi dan spasi → Gunakan indentasi serta baris kosong agar lebih mudah dibaca, dan pisahkan informasi parameter serta return secara jelas.

Best Practice

• Deskripsi singkat dan jelas → docstring harus ringkas, tapi cukup informatif untuk menjelaskan fungsi/kegunaan.
• Konsistensi gaya → Gunakan gaya docstring yang konsisten di seluruh proyek, misalnya Google Style atau NumPy Style, agar mudah dibaca.

5. Pengujian dengan docstring (doctest)

Python memiliki modul doctest yang memungkinkan pengujian otomatis terhadap contoh kode dalam docstring. Dengan ini, Anda bisa memastikan contoh yang ditulis benar-benar berjalan sesuai harapan, sehingga meningkatkan keandalan kode.

Cara Dasar Menggunakan doctest

doctest akan mendeteksi contoh kode di dalam docstring dan membandingkan output-nya. Tambahkan blok berikut untuk menjalankan pengujian:

def add(a, b):
    """
    Menjumlahkan dua angka dan mengembalikan hasilnya.

    Args:
        a (int): Angka pertama
        b (int): Angka kedua

    Returns:
        int: Hasil penjumlahan

    Example:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()

Jika berhasil, tidak ada output yang muncul. Jika gagal, pesan error akan ditampilkan. Dengan demikian, docstring tetap selaras dengan kode nyata.

Keuntungan Menggunakan doctest

1. Konsistensi kode → memastikan contoh dalam dokumentasi sesuai dengan implementasi nyata.
2. Otomatisasi pengujian → cukup jalankan doctest, semua contoh dalam docstring langsung diuji, sehingga meminimalkan kesalahan.

6. Contoh Praktis: Dokumentasi Kode dengan docstring

Menggunakan docstring membuat kode Python lebih mudah dipahami. Berikut contoh penerapan pada kelas dan metode, lalu didokumentasikan otomatis dengan Sphinx.

Contoh docstring pada Kelas

class Calculator:
    """
    Kelas kalkulator sederhana.

    Menyediakan operasi dasar: tambah, kurang, kali, bagi.

    Attributes:
        result (int): variabel untuk menyimpan hasil perhitungan
    """

    def __init__(self):
        """
        Konstruktor Calculator.
        Hasil awal diatur ke 0.
        """
        self.result = 0

    def add(self, a, b):
        """
        Menjumlahkan dua angka dan mengembalikan hasilnya.

        Args:
            a (int): Angka pertama
            b (int): Angka kedua

        Returns:
            int: Hasil penjumlahan
        """
        self.result = a + b
        return self.result

Generasi Dokumentasi dengan Sphinx

Dengan Sphinx, docstring bisa diubah menjadi dokumentasi HTML atau PDF secara otomatis.

Instalasi:

pip install sphinx

Inisialisasi proyek:

sphinx-quickstart

Kemudian jalankan:

make html

Hasilnya, docstring dari kode Python akan terkonversi menjadi dokumentasi siap pakai.

7. Kesalahan Umum dan Cara Menghindarinya

Saat menulis docstring, pemula sering membuat kesalahan. Berikut beberapa contoh dan cara memperbaikinya.

1. Deskripsi yang terlalu umum

docstring harus jelas dan ringkas. Deskripsi yang terlalu samar tidak membantu pembaca memahami maksud fungsi.

def add(a, b):
    """Menambahkan dua angka."""
    return a + b

Masalah: tidak menjelaskan tipe data parameter atau nilai kembali. Perbaikan:

def add(a, b):
    """
    Menjumlahkan dua bilangan bulat dan mengembalikan hasilnya.

    Args:
        a (int): Angka pertama
        b (int): Angka kedua

    Returns:
        int: Hasil penjumlahan
    """
    return a + b

2. Penjelasan parameter dan return yang tidak lengkap

Jika parameter atau nilai kembali tidak dijelaskan dengan detail, pengguna bisa salah dalam menggunakan fungsi.

def divide(a, b):
    """Membagi dua angka."""
    return a / b

Masalah: tidak menyebutkan tipe data dan kemungkinan error. Perbaikan:

def divide(a, b):
    """
    Membagi dua angka dan mengembalikan hasilnya. Jika pembagi bernilai 0, akan muncul ZeroDivisionError.

    Args:
        a (float): Angka yang dibagi
        b (float): Angka pembagi

    Returns:
        float: Hasil pembagian

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

Dengan memberikan informasi lengkap di docstring, fungsi lebih mudah dipahami dan digunakan dengan benar.

8. Ringkasan: Dokumentasi Efektif dengan docstring

Artikel ini menjelaskan pentingnya docstring, cara penulisan, gaya umum, best practice, serta integrasi dengan alat seperti doctest dan Sphinx.

Konsistensi dengan PEP 257

Dengan mengikuti PEP 257, Anda bisa membuat dokumentasi yang konsisten, baik berupa docstring satu baris maupun multi-baris.

Pengujian dengan doctest

Menggunakan doctest membantu memastikan contoh kode dalam dokumentasi selalu valid dan sesuai implementasi nyata.

Dokumentasi Otomatis dengan Sphinx

Dengan Sphinx, docstring bisa langsung diubah menjadi dokumentasi HTML/PDF yang selalu mengikuti perubahan kode, sehingga mempermudah pemeliharaan proyek.