Рекомендации по работе с функциями и классами для Python

Я ищу лучшие практики для документации по функциям/классу/модулю, т.е. комментарии в самом коде. В идеале я бы хотел создать шаблон комментария, который будет доступен для чтения и использования человеком с помощью утилит документации Python.

Я прочитал документацию Python для docstrings.

Я понимаю эту часть:

В первой строке всегда должно быть краткое краткое изложение цели объектов. Для краткости он не должен явно указывать имя или тип объектов, поскольку они доступны другими средствами (за исключением того, что имя является глаголом, описывающим операцию функций). Эта строка должна начинаться с заглавной буквы и заканчиваться периодом.

Если в строке документации больше строк, вторая строка должна быть пустой, визуально отделяя итоговую информацию от остальной части описания.

Это предложение нуждается в более подробном объяснении:

Следующие строки должны содержать один или несколько абзацев, описывающих соглашения об объектах, их побочные эффекты и т.д.

В частности, я ищу примеры хорошо прокомментированных функций и классов.

Ответ 1

Вы должны использовать reStructuredText и проверить конструкции разметки Sphinx. Все классные дети это делают.

Вы должны следовать соглашениям docstring. то есть.

Он предписывает функцию или метод эффект как команда ( "Сделайте это", "Вернуть это" ).

Вам следует избегать ненужного повторения или объяснения чрезвычайно очевидных. Пример того, что не делать:

def do_things(verbose=False):
    """Do some things.
    :param verbose: Be verbose (give additional messages).
    """
    raise NotImplementedError

Если бы вы хотели описать что-то неочевидное, это была бы другая история; например, эта подробная информация вызывает сообщения в потоке stdout или logging. Это не относится к Python, но следует из более ручных волновых идеалов, таких как самодокументирующий код и код/​​документация DRY.

Старайтесь избегать упоминания конкретных типов, если это возможно (абстрактные или интерфейсные типы обычно в порядке). Упомянутые протоколы обычно более полезны с точки зрения печати утки (т.е. "Итерируемый" вместо set, или "измененная упорядоченная последовательность" вместо list). Я видел некоторый код, который является очень буквальным и тяжелым WRT :rtype: и :type param: документацией на уровне функций, которая, как мне показалось, не согласуется с менталитетом утиной печати. ​​

Ответ 2

Как сказал Эмджи, Django - хороший проект для четких, последовательных руководств по стилю.

Например, их Contribute to Django style guide даже доходит до описания того, как они хотели бы видеть документацию. В частности, они упоминают:

В docstrings используйте "слова действия", например:

def foo():
    """
    Calculates something and returns the result.
    """
    pass

Вот пример того, что не делать:

def foo():
    """
    Calculate something and return the result.
    """
    pass

Ответ 3

Я думаю, что лучший ресурс будет Документирование Python

Цитата:

В этом документе описывается руководство по стилю для нашей документации, настраиваемая разметка reStructuredText, представленная для поддержки документации Python и того, как она должна использоваться, а также системы сборки Sphinx.

Sphinx: официальный генератор документации Python

Ответ 4

Лучший способ изучить методы документации - это, вероятно, посмотреть исходный код хорошо известного проекта. Как Djangoproject.

Ответ 5

Существует не менее 3 разных стилей: традиционная docstring, Google и NumPy. Первый из них довольно хорошо поддерживается такими инструментами, как PyCharm IDE и тем, что я обычно использую. Обратите внимание, что все 3 стиля поддерживают reStructuredText, который является расширенной уценкой, как показано ниже.

Традиционная docstring

Вот полный пример с часто используемыми элементами.

"""
.. module:: write your comments anywhere including classes
.. note:: you can use these elements anywhere   
.. moduleauthor:: My Name <[email protected]>
"""

def function1(self, arg1, arg2):
    """This is short explanation

    This is a longer explanation, with latex syntax :math:`\\alpha`.
    You can have many lines here.

    **Make this bold**:
     - Bullet point 1
     - Bullet point 2

    :param arg1: the first value
    :param arg2: the 2nd value
    :type arg1: int, float,...
    :returns: some value
    :rtype: int, float

    :Example:

    >>> import something
    >>> function1(0, 1.0)
    2

    .. note:: This will be in a box
    .. seealso:: :class:`MyOtherClass`
    .. warning:: This will be in red box
    .. todo:: this will be in orange box
    """
    return 0

Стиль Google

стиль Google более читабельен для пользователя и обычно также хорошо поддерживается с расширениями, такими как Napoleon.

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

Стиль NumPy

Стиль NumPy/SciPy очень похож на Google, но с другим (и более подробным) форматированием.

def function_with_types_in_docstring(param1, param2):
    """Example function with types documented in the docstring.

    `PEP 484`_ type annotations are supported. If attribute, parameter, and
    return types are annotated according to `PEP 484`_, they do not need to be
    included in the docstring:

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : str
        The second parameter.

    Returns
    -------
    bool
        True if successful, False otherwise.

    .. _PEP 484:
        https://www.python.org/dev/peps/pep-0484/

    """

Как создать документацию

Чтобы завершить ответ, выполните быстрые шаги для создания файла документации из кода:

sudo pip install sphinx
sphinx-quickstart
cd docs
make html
open _build/html/index.html

Подробнее здесь