Docstrings vs Комментарии

Я немного смущен различием между docstrings и комментариями в python.

В моем классе мой учитель представил что-то, известное как "рецепт дизайна", набор шагов, который, предположительно, поможет нам обучить студентов и организовать наше кодирование лучше на Python. Из того, что я понимаю, ниже приведен пример шагов, которым мы следуем - это так называется рецепт дизайна (материал в цитатах):

def term_work_mark(a0_mark, a1_mark, a2_mark, ex_mark, midterm_mark):

    ''' (float, float, float, float, float) -> float

    Takes your marks on a0_mark, a1_mark, a2_mark, ex_mark and midterm_mark, 
    calculates their respective weight contributions and sums these 
    contributions to deliver your overall term mark out of a maximum of 55 (This
    is because the exam mark is not taken account of in this function)

    >>>term_work_mark(5, 5, 5, 5, 5)
    11.8
    >>>term_work_mark(0, 0, 0, 0, 0)
    0.0
    '''

    a0_component = contribution(a0_mark, a0_max_mark, a0_weight)
    a1_component = contribution(a1_mark, a1_max_mark, a1_weight)
    a2_component = contribution(a2_mark, a2_max_mark, a2_weight)
    ex_component = contribution(ex_mark, exercises_max_mark,exercises_weight)
    mid_component = contribution(midterm_mark, midterm_max_mark, midterm_weight)
    return (a0_component + a1_component + a2_component + ex_component + 
            mid_component)

Насколько я понимаю, это, в основном, docstring, и в нашей версии docstring он должен включать три вещи: описание, примеры того, что ваша функция должна делать, если вы вводите его в оболочку python, и тип контракт ", раздел, который показывает вам, какие типы вы вводите, и какими типами функция вернется.

Теперь все хорошо и сделано, но наши задания требуют от нас также комментариев, которые объясняют природу наших функций, используя символ токена "#".

Итак, мой вопрос: не я уже объяснил, что моя функция будет делать в разделе описания docstring? Какой смысл добавлять комментарии, если я по существу расскажу читателю то же самое?

Кроме того, на стороне заметки, у меня есть абсолютно ужасающее время, пытаясь заставить этот код правильно выходить один раз в фактический пост. Извини за это. Я не предполагал, что кто-то может указать мне в правильном направлении правильно форматировать код в сообщении?

Ответы

Ответ 1

Кажется, ваш учитель является поклонником "Как создавать программы";)

Я бы решил это как писать для двух разных аудиторий, которые не всегда будут перекрываться.

Сначала есть докстры; они предназначены для людей, которые будут использовать ваш код, не нуждаясь или не желая знать, как это работает. Докстры можно превратить в фактическую документацию. Рассмотрите официальную документацию на Python: что доступно в каждой библиотеке и как ее использовать, нет сведений о реализации (если они напрямую не связаны с использованием)

Во-вторых, есть комментарии в коде; это объяснить, что происходит с людьми (как правило, вы!), которые хотят расширить код. Обычно они не превращаются в документацию, поскольку они действительно касаются самого кода, а не использования. Сейчас существует столько мнений о том, что делает для хороших комментариев (или их отсутствия), поскольку есть программисты. Мои личные эмпирические правила для добавления комментариев объясняют:

Части кода, которые обязательно сложны. (Оптимизация приходит на ум)
Обходные пути для кода, который у вас не контролируется, который в противном случае может выглядеть нелогичным.
Я тоже признаюсь в TODO, хотя я стараюсь свести это к минимуму
Где я сделал выбор более простого алгоритма, где более эффективная (но более сложная) опция может идти, если производительность в этом разделе становится критически важной.

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

Ответ 2

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

И о комментариях и строках doc, строка doc объясняет общее использование и базовую информацию о методах. С другой стороны, комментарии предназначены для предоставления конкретной информации о блоках или строках, #TODO используется, чтобы напомнить вам, что вы хотите делать в будущем, определение переменных и так далее. Кстати, в IDLE строка doc отображается как подсказка, когда вы наводите курсор на имя метода.

Ответ 3

Цитата из этой страницы http://www.pythonforbeginners.com/basics/python-docstrings/

Строки документации Python (или docstrings) обеспечивают удобный способ связывания документации с модулями, функциями, классами Python, и методы.

Объект docsting определяется включением строковой константы в качестве первый оператор в определении объекта.

Он указан в исходном коде, который используется, как комментарий, для документируйте определенный сегмент кода.

В отличие от обычных комментариев исходного кода, docstring должен описывать что делает функция, а не как.

Все функции должны иметь docstring

Это позволяет программе проверять эти комментарии во время выполнения, для экземпляр как интерактивная справочная система или метаданные.

Докстры могут быть доступны с помощью атрибута __ doc __ на объектах.

Доступ к Docstrings можно получить через программу (__doc__), где недоступны доступ к встроенным комментариям.
Интерактивные справочные системы, такие как bpython и IPython, могут использовать docstrings для отображения docsting во время разработки. Чтобы вы не посещали программу каждый раз.

Ответ 4

Я считаю, что стоит упомянуть, что говорит PEP8, я имею в виду чистую концепцию.

Строки документации

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

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

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

Optional plotz says to frobnicate the bizbaz first.
"""
Для одной строки docstrings держите закрытие "" в той же строке.

Обычно применяются к некоторому (или всем) коду, который следует за ними, и отступы на том же уровне, что и этот код. Каждая строка комментария блока начинается С# и одного пробела (если только текст не заключен в комментарий).

Параграфы внутри комментария блока разделяются линией, содержащей один #.

Встроенные комментарии

Используйте встроенные комментарии экономно.

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

Встроенные комментарии не нужны и на самом деле отвлекают, если они указывают очевидное.

Не делайте этого:

x = x + 1 # Приращение x

Но иногда это полезно:

x = x + 1 # Компенсация для границы