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

Question

Я немного смущен различием между 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 должна включать три вещи: описание, примеры того, что должна делать ваша функция, если вы введете ее в оболочку python и «контракт типа», раздел, который показывает вам, какие типы вы вводите, и какие типы функции вернется.

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

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

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

Answer 1

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

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

Answer 2

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

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

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

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

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

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

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

можно Строки документации обращаться по __ док __ атрибута объектов.

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

Answer 3

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

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

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

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

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

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

Answer 4

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

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

Условные обозначения для написания хороших струне документация (А.К.А. «)» строки документации увековечены в PEP 257.

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

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

"""Return a foobang 

Optional plotz says to frobnicate the bizbaz first. 
""" 

Для одного вкладыша строки документации, пожалуйста, держать закрытие„“» на той же линии.

Комментарии

Блок комментарии

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

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

Инлайн Комментарии

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

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

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

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

х = х + 1 # Increment х

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

х = х + 1 # Компенсация за границу

Ссылка

• https://www.python.org/dev/peps/pep-0008/#documentation-strings
• https://www.python.org/dev/peps/pep-0008/#inline-comments
• https://www.python.org/dev/peps/pep-0008/#block-comments
• https://www.python.org/dev/peps/pep-0257/