Является ли хорошей практикой использование тройных кавычек для создания «строк документации» в нестандартных контекстах?

Question

Я смотрю на чей-то код, у которого повсюду такие "строки документации":

SLEEP_TIME_ON_FAILURE = 5
"""Time to keep the connection open in case of failure."""

SOCKET_TIMEOUT = 15
"""Socket timeout for inherited socket."""

...

Согласно документации Python, строки документации применимы только в контексте начала модуля, класса или метода.

Какое значение имеет вышеуказанная нестандартная практика? Почему Python это позволяет? Разве это не влияет на производительность?

Answer 1

В python """ - это синтаксис для многострочной строки.

s1 = """This is a multi-line string."""
s2 = """This is also a multi-line
string that stretches 
across multiple lines"""

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

Единственное исключение из этого правила - это когда строка документации идет сразу после определения функции или класса или поверх модуля . В этом случае он сохраняется в специальной переменной __doc__.

Согласно PEP8 ,

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

Запись строк документации для всех общедоступных модулей, функций, классов и методов. Строки документации не нужны для закрытых методов, но у вас должен быть комментарий, описывающий, что делает метод. Этот комментарий должен появиться после строки def.

Answer 2

Что касается Python, это не строки документации. Это просто строковые литералы, используемые как выражения выражений. Вы можете сделать это - вы можете использовать любое допустимое выражение Python в качестве своего собственного выражения. Python не волнует, действительно ли выражение что-либо делает. Для строки в отдельной строке единственным влиянием на производительность является очень небольшое количество дополнительной работы во время компиляции байт-кода; это не влияет на время выполнения, так как эти строки оптимизируются.

Некоторые генераторы документации смотрят на эти строки. Например, очень распространенное расширение Sphinx autodoc будет анализировать эти строки для документирования того, что находится непосредственно над ними. Проверьте, используете ли вы что-нибудь подобное, прежде чем менять код.

Answer 3

В этих случаях вы должны использовать встроенный комментарий, который четко определено в руководстве по стилю PEP8 https://www.python.org/dev/peps/pep-0008/#comments, например ::

SLEEP_TIME_ON_FAILURE = 5  # Time to keep the connection open in case of failure

SOCKET_TIMEOUT = 15  # Socket timeout for inherited socket