Как писать значащие докстры?

Что, по вашему мнению, является значимым документом? Что вы ожидаете от описания там?

Например, рассмотрим этот класс Python __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

Вы находите это значимым? Опубликуйте свои хорошие/плохие примеры для всех, чтобы знать (и общий ответ, чтобы его можно было принять).

Ответ 1

Я согласен с "Все, что вы не можете сказать по сигнатуре метода". Это также может означать, что возвращает метод/функция.

Вы также можете использовать Sphinx (и синтаксис reStructuredText) для целей документации внутри ваших docstrings. Таким образом, вы можете легко включить это в свою документацию. Например, проверьте, например. repoze.bfg, который использует этот экстенсивно (примерный файл, пример документации).

Еще одна вещь, которую можно положить в docstrings, также doctests. Это может иметь смысл. для модулей или классов docstrings, так как вы также можете показать, как использовать и одновременно тестировать.

Ответ 2

От PEP 8:

Соглашения о написании строк хорошей документации (a.k.a. "docstrings" ) увековечены в PEP 257.

Пишите docstrings для всех открытых модулей, функций, классов и методов. Докстеллы не нужны для непубличных методов, но вы должен иметь комментарий, который описывает, что делает метод. Эта комментарий должен появиться после строки "def".

PEP 257 описывает хорошие соглашения с docstring. Обратите внимание, что наиболее важно, что "", которое заканчивается многострочной docstring, должно быть на линией, и предпочтительно ей предшествует пустая строка.

В случае с одним лайнером docstrings, все в порядке, чтобы сохранить закрытие "" в той же строке.

Ответ 3

Что должно там идти:

Все, что вы не можете сказать по сигнатуре метода. В этом случае единственным полезным битом является: displayName - если пустым будет установлено имя поля.

Ответ 4

Посмотрите на числовые значки numpy для хороших примеров (например, http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

Докстоны разбиваются на несколько разделов и выглядят так:

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents

Ответ 5

Самые яркие вещи, которые я могу придумать для включения в docstring, - это вещи, которые не очевидны. Обычно это включает информацию о типе или требования к возможностям - например. Msgstr "Требуется файл-подобный объект". В некоторых случаях это будет видно из подписи, а не в других случаях.

Еще одна полезная вещь, которую вы можете добавить в свои docstrings, - doctest.

Ответ 6

Мне нравится использовать документацию, чтобы максимально подробно описать, что делает функция, особенно поведение в угловых случаях (случаи краев a.k.a.). В идеале программист, использующий эту функцию, никогда не должен смотреть на исходный код - на практике это означает, что всякий раз, когда другой программист должен смотреть на исходный код, чтобы выяснить некоторые детали того, как работает эта функция, эта деталь, вероятно, должна была быть упомянутых в документации. Как сказал Фредди, все, что не добавляет каких-либо подробностей к сигнатуре метода, вероятно, не должно быть в строке документации.

Ответ 7

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