строка документа в классе или конструктор __init__? - PullRequest
0 голосов
/ 15 января 2019

Кажется, есть два места, где вы можете поместить строки документации для класса:

  1. Прямо под определением класса:
class MyClass(object):
     """ Summary of MyClass

     Body

     ...
     """
  1. Прямо под конструктором __init__:
...
    def __init__(self, arg1, arg2):
        """ Summary of MyClass

        Body

        ...
        """

Что предпочтительнее? Или все в порядке?

1 Ответ

0 голосов
/ 15 января 2019

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

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

Акцент мой. Эта ссылка взята из PEP 257 - Соглашения о документах

...