Как писать осмысленные комментарии?

что, на ваш взгляд, является значимой docstring? Что вы ожидаете там описать?

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

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

25
comments docstring python

7 ответов

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

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

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

14

с PEP 8:

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

  • запись docstrings для всех общедоступных модулей, функций, классов и методов. Комментарии не нужны для непубличных методов, но вы должен иметь комментарий, который описывает, что делает метод. Этот комментарий должен появиться после строки "def".
  • Пеп 257 описывает хорошие соглашения docstring. Обратите внимание, что самое главное,"", который заканчивается многострочной docstring должен быть на строка сама по себе, и предпочтительно перед пустой строкой.
  • для одного лайнера docstrings, это нормально, чтобы держать закрытие "" на той же линии.
9

Что будет:

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

6

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

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

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
6

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

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

2

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

1

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

0