# درباره docstring و استاندارد‌های آن

یک docstring پایتون رشته ای است که برای مستند سازی ماژول، کلاس، فانکشن یا متد پایتون استفاده می شود، بنابراین برنامه نویسان می توانند بدون نیاز به خواندن جزئیات پیاده سازی، بدانند که چه کاری انجام می دهد. همچنین ، ایجاد یک سند آنلاین (html) به طور خودکار از docstrings یک روش معمول است.

مثال بعدی ایده ای را در مورد شکل یک docstring ارائه می دهد:

def add(num1, num2):
    """
    Add up two integer numbers.

    This function simply wraps the ``+`` operator, and does not
    do anything interesting, except for illustrating what
    the docstring of a very simple function looks like.

    Parameters
    ----------
    num1 : int
        First number to add.
    num2 : int
        Second number to add.

    Returns
    -------
    int
        The sum of ``num1`` and ``num2``.

    See Also
    --------
    subtract : Subtract one integer from another.

    Examples
    --------
    >>> add(2, 2)
    4
    >>> add(25, 0)
    25
    >>> add(10, -10)
    0
    """
    return num1 + num2

برخی از استانداردها در مورد docstringها وجود دارد که خواندن آنها را آسان تر می کند و اجازه می دهد به راحتی به فرمت های دیگر مانند html یا pdf صادر شود.

خوب:

def add_values(arr):
    """
    Add the values in ``arr``.

    This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.

    Some sections are omitted here for simplicity.
    """
    return sum(arr)

بد:

def func():

    """Some function.

    With several mistakes in the docstring.

    It has a blank like after the signature ``def func():``.

    The text 'Some function' should go in the line after the
    opening quotes of the docstring, not in the same line.

    There is a blank line between the docstring and the first line
    of code ``foo = 1``.

    The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar