Как писать значащие docstrings?

Question

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

Для примера рассмотрим этот класс в 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 
    """ 

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

Answer 1

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

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

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

Answer 2

Что должно пойти туда:

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

Answer 3

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

Answer 4

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

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

Answer 5

От PEP 8:

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

• Написать docstrings для всех открытых модулей, функций, классов и методов. Docstrings не нужны для непубличных методов, но у вас должен быть комментарий, который описывает, что делает этот метод. Этот комментарий должен появиться после строки «def».
• PEP 257 описывает хорошие соглашения с docstring. Обратите внимание, что самое главное, что «" », которое заканчивается многострочной docstring, должно быть на линии само по себе и предпочтительно должно предшествовать пустой строке.
• Для одного вкладыша строки документации, это нормально держать закрытие «»»на ту же строку. Строка документация

Answer 6

ЗАКАНЧИВАТЬ 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 

Answer 7

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