Существуют ли соглашения для комментариев модуля Python?

Question

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

Однако я виделследующие в комментариях и строки документов:

__author__ = "..."
__version__ = "..."
__date__ = "..."

Где находится правильное место для размещения таких предметов?Какие другие __[name]__ переменные являются общими для перечисления в верхней части модулей?

Answer 1

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

__version__ упоминается в Руководстве по стилю Python .

Что касается строк документации, для вас есть PEP !

Строка документации для модуля должна вообще перечислите классы, исключения и функции (и любые другие объекты) которые экспортируются модулем, с резюме в одну строку каждого. (Эти резюме обычно дают меньше деталей чем итоговая строка в объекте Строка документа.) Строка документа для пакет (то есть, строка документа модуль init .py) должен также перечислите модули и подпакеты экспортируется посылкой.

Answer 2

Вы можете взглянуть на:

• Epydoc , более конкретно его предопределенные поля .
• Pydoc

Answer 3

Я бы предложил не беспокоиться о __author__, __version__ и т. Д. Эти атрибуты в любом случае обрабатываются любой приличной системой контроля версий.Добавляйте их только в том случае, если вам нужна эта информация в производственной системе, исходный код которой уже был экспортирован из системы управления версиями.