Должна ли документация расширенных методов включать документацию базового метода?

Должна ли документация расширенных методов включать документацию базового метода?
Должна ли документация расширенных методов включать документацию базового метода? - andrewtneel @ Unsplash

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

Этот дочерний метод должен делать то же самое, что и родительский метод, с небольшими изменениями.

В этом случае, в документации дочернего метода, полезно ли освещать то, что делает родительский метод?

  • Если мы это сделаем, то дочерний метод будет "самоподдерживающимся", но родительский метод может быть изменен, и дочерний документ станет устаревшим или даже ложным.

  • Если этого не сделать, нам придется переходить от дочернего метода к родительскому, чтобы получить полную картину, что может раздражать

class Parent:

    def some_method(self):
        """
        This method does A and B
        """

class Child(Parent):

    def some_method(self):
        """
        This method also does extra C
        """

Помимо ваших мнений и предпочтений (которые я с удовольствием выслушаю), есть ли у нас "канонические" источники, например, авторитетные книги по этому вопросу?

Edit: Я вижу, что, включив тупую реализацию в примеры выше, я запутал вопрос, заставив думать, что документация была о деталях реализации. Это не так, поэтому давайте уберем реализацию. Я думаю, что проблема все еще в силе со своими плюсами и минусами (дублирование документации потенциально вредно, как дублирование кода против самоподдерживающейся документации).

Давайте придерживаться вашего примера: docstring в дочернем классе может быть либо

    """
    This method does A and B, followed by C
    """

или

    """
    This method is an extension of Parent.some_method, 
    it does exactly the same operation, then followed by C
    """

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

Во втором случае все ровно наоборот: для читателя это недостаток, а для вашего обслуживания - преимущество.

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


LetsCodeIt, 31 декабря 2022 г., 21:45