Apa itu Docstring

In Python, a docstring is a string literals that appears as the first statement in a module, function, class, or method definition. The purpose of a docstring is to provide documentation about the purpose, behavior, and usage of the code that follows it. A docstring can be a single-line or multi-line string, and it can be written using single or double quotes.

Mengapa Docstring Penting

Berikut adalah beberapa alasan mengapa docstring penting dalam Python:

• Ketegasan dan Keterbacaan
  Docstring membantu membuat kode lebih mudah dibaca dan dipahami dengan memberikan penjelasan yang jelas tentang apa yang dilakukan oleh kode dan cara menggunakannya. Dengan membaca docstring, seorang pengembang dapat dengan cepat memahami tujuan dari sebuah fungsi, kelas, atau modul, dan bagaimana itu dapat digunakan dalam kode mereka sendiri.

• Dokumentasi
  Docstring berfungsi sebagai cara untuk mendokumentasikan kode, sehingga lebih mudah bagi pengembang lain untuk memahami cara kerjanya dan cara menggunakannya. Hal ini terutama penting saat bekerja pada proyek besar, di mana beberapa pengembang dapat bekerja pada kode yang sama.

• Perawatan dan Refaktor
  Docstring dapat berguna dalam hal perawatan dan refaktor kode. Mereka memberikan referensi tentang apa yang dilakukan oleh kode, sehingga memudahkan untuk mengidentifikasi apa yang perlu diubah dan bagaimana melakukannya.

• Pengujian dan Debugging
  Docstring dapat digunakan untuk menguji dan men-debug kode. Dengan memberikan penjelasan yang jelas tentang apa yang seharusnya dilakukan oleh kode, pengembang dapat memastikan bahwa kode mereka bekerja sesuai yang diharapkan.

Format Docstring

Di Python, ada beberapa format yang berbeda untuk menulis docstring. Format yang Anda pilih akan tergantung pada preferensi pribadi Anda, serta pedoman atau konvensi yang Anda ikuti, seperti yang ditetapkan dalam pustaka standar Python atau dalam panduan gaya pihak ketiga. Berikut adalah beberapa format docstring paling umum dalam Python.

reStructuredText (reST) Format

reStructuredText (reST) adalah bahasa markup ringan yang digunakan untuk membuat dokumentasi dalam Python, serta dalam bahasa pemrograman lainnya. Dirancang untuk mudah dibaca dan ditulis, dan untuk menyediakan format yang fleksibel dan dapat diperluas untuk membuat dokumentasi.

Berikut adalah contoh docstring Python dalam format reST:

def my_function(arg1, arg2):
    """
    Brief description of the function.

    A longer description that goes into more detail about the function and how it works.

    :param arg1: Description of arg1.
    :type arg1: int
    :param arg2: Description of arg2.
    :type arg2: str
    :return: Description of the return value.
    :rtype: bool
    :raises ValueError: If the function encounters a value error.
    """
    # function code goes here

Pada contoh ini, docstring dimulai dengan ringkasan singkat tentang apa yang dilakukan oleh fungsi, diikuti dengan deskripsi lebih panjang yang memberikan lebih banyak detail. Parameter didokumentasikan menggunakan direktif :param dan :type, dan nilai kembalian didokumentasikan menggunakan direktif :return dan :rtype. Direktif :raises digunakan untuk mendokumentasikan setiap pengecualian yang mungkin dihasilkan oleh fungsi.

Format reST sangat fleksibel dan dapat diperluas, dan dapat digunakan untuk membuat berbagai format dokumentasi, termasuk HTML, LaTeX, dan PDF. Ini juga mudah dipelajari dan digunakan, sehingga menjadi pilihan populer bagi pengembang Python.

Format Google-Style

Format Google-Style adalah format populer untuk docstring yang digunakan oleh Google dan banyak proyek open-source lainnya. Ini dirancang untuk menjadi sederhana dan mudah dibaca, dengan fokus pada kejelasan dan konsistensi.

Berikut adalah contoh docstring Python dalam format Google-Style:

def my_function(arg1, arg2):
    """
    Brief description of the function.

    A longer description that goes into more detail about the function and how it works.

    Args:
        arg1 (int): Description of arg1.
        arg2 (str): Description of arg2.

    Returns:
        bool: Description of the return value.

    Raises:
        ValueError: If the function encounters a value error.
    """
    # function code goes here

Pada contoh ini, dokstring dimulai dengan ringkasan singkat tentang apa yang dilakukan oleh fungsi, diikuti dengan deskripsi yang lebih panjang yang memberikan lebih banyak detail. Bagian Args mencakup deskripsi dari setiap parameter, serta tipenya. Bagian Returns mencakup deskripsi dari apa yang dikembalikan oleh fungsi, serta tipenya. Bagian Raises mencakup pengecualian apa pun yang mungkin ditimbulkan oleh fungsi.

Format gaya Google mudah dibaca dan dipahami, serta dapat membantu pengembang lain yang menggunakan kode Anda. Format ini juga relatif ringkas, yang dapat membantu dalam mendokumentasikan fungsi atau perpustakaan yang kompleks.

Format NumPy-Style

Format NumPy-style adalah format dokstring yang digunakan oleh perpustakaan NumPy dan banyak paket Python ilmiah lainnya. Format ini dirancang untuk konsisten dengan gaya dokumentasi NumPy dan menyediakan cara yang jelas dan terstruktur untuk mendokumentasikan fungsi dan perpustakaan ilmiah.

Berikut adalah contoh dokstring Python dalam format NumPy-style:

def my_function(arg1, arg2):
    """
    Brief description of the function.

    Parameters
    ----------
    arg1 : int
        Description of arg1.
    arg2 : str
        Description of arg2.

    Returns
    -------
    bool
        Description of the return value.

    Raises
    ------
    ValueError
        If the function encounters a value error.
    """
    # function code goes here

Pada contoh ini, dokstring dimulai dengan ringkasan singkat tentang apa yang dilakukan oleh fungsi, diikuti dengan bagian Parameters yang mencakup deskripsi dari setiap parameter, serta tipenya. Bagian Returns mencakup deskripsi dari apa yang dikembalikan oleh fungsi, serta tipenya. Bagian Raises mencakup pengecualian apa pun yang mungkin ditimbulkan oleh fungsi.

Format gaya NumPy sangat berguna untuk fungsi dan perpustakaan ilmiah, karena menyediakan cara yang konsisten untuk mendokumentasikan algoritma dan perhitungan yang kompleks. Format ini juga memungkinkan penggunaan notasi dan format matematika, yang dapat membantu dalam mendokumentasikan kode ilmiah.

Referensi

https://peps.python.org/pep-0257/
https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
https://betterprogramming.pub/3-different-docstring-formats-for-python-d27be81e0d68
https://google.github.io/styleguide/pyguide.html