---
## 📝 Docstring

Одна из важных вещей в любом коде – **читабельность**.
Однако не всегда получается оптимизировать алгоритмы или названия переменных, функций,
методов или классов для полного понимания кода. Для этого нам нужны docstring. <br>
Docstring пишется только для объемных и сложных задач
(наличие множества переменных, длинной цепочки построения логики и т.д.). <br><br>
<b>Обновление 04.04.2024:</b> docstring пишутся по правилам google. https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html <br><br>
В самих docstring описываются как минимум 4 вещи:
1. основная идея функции, метода или класса;
2. род используемых переменных (Опционально, если не указана аннотация);
3. исключения (Если добавлено больше чем одно исключение или исключение является кастомное);
4. ожидаемый результат, то есть то, что мы получаем на выходе (этой частью можно пренебрегать,
если указан ожидаемый тип ответа после аргументов; например, def sum(a, b) -> int) <br><br>
В основном docstring пишутся на английском. Например:
<pre>
<code>
def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    The format for a parameter is::

        name (type): description
            The description may span multiple lines. Following
            lines should be indented. The "(type)" is optional.

            Multiple paragraphs are supported in parameter
            descriptions.

    Args:
        param1 (int): The first parameter.
        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.

    Returns:
        bool: True if successful, False otherwise.

        The return type is optional and may be specified at the beginning of
        the ``Returns`` section followed by a colon.

        The ``Returns`` section may span multiple lines and paragraphs.
        Following lines should be indented to match the first line.

        The ``Returns`` section supports any reStructuredText formatting,
        including literal blocks::

            {
                'param1': param1,
                'param2': param2
            }

    Raises:
        AttributeError: The ``Raises`` section is a list of all exceptions
            that are relevant to the interface.
        ValueError: If `param2` is equal to `param1`.
    """
    if param1 == param2:
        raise ValueError('param1 may not be equal to param2')
    return True
</code>
</pre>
**_N.B._**: не забываем про аннотацию, в особенности когда определяется класс или комплексная функция !

---