Готовый перевод Style Guide for Python Code: Documentation Strings

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

Пишете docstrings для public модулей, функций, классов и методов.

Docstrings не обязательны для не public методов, но вам следует ставить комменатрии, которые описывают, что метод выполняет.

Комментарий должен появиться после строки c определенем "def".

PEP 257 описывает хорошие соглашения по docstrings.

Имейте в виду, что наиболее важно, чтобы """, которая закрывает многострочные docstrings, должны быть на отдельной строке, и желательно после них была пустая линия, как здесь:

"""Возвращаем foobang

Необязательный plotz говорит, что он бесцельно манипулирует bizbaz первым.

"""

Для однострочных docstrings, ничего что закрывающие """ находятся на одной линии.

Переведено на Нотабеноиде
http://notabenoid.org/book/1336/5354

Переводчики: wuffur