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

1. Apa itu docstring di Python?

Posisi dan Format docstring

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

2. Cara Dasar Menulis docstring

Struktur Dasar docstring

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

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

Ad

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

Google Style

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

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

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

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.

Ad

5. Pengujian dengan docstring (doctest)

Cara Dasar Menggunakan doctest

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()

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

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

pip install sphinx

sphinx-quickstart

make html

7. Kesalahan Umum dan Cara Menghindarinya

1. Deskripsi yang terlalu umum

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

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

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

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

8. Ringkasan: Dokumentasi Efektif dengan docstring

Konsistensi dengan PEP 257

Pengujian dengan doctest

Dokumentasi Otomatis dengan Sphinx

Ad