Допустим, некоторый метод родительского класса повторно реализован в дочернем классе.
Этот дочерний метод должен делать то же самое, что и родительский метод, с небольшими изменениями.
В этом случае, в документации дочернего метода, полезно ли освещать то, что делает родительский метод?
Если мы это сделаем, то дочерний метод будет "самоподдерживающимся", но родительский метод может быть изменен, и дочерний документ станет устаревшим или даже ложным.
Если этого не сделать, нам придется переходить от дочернего метода к родительскому, чтобы получить полную картину, что может раздражать
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.
Во втором случае все ровно наоборот: для читателя это недостаток, а для вашего обслуживания - преимущество.
Выбор между этими двумя подходами часто является суждением. Определенное количество избыточности в документации, конечно, нормально и помогает сделать ее более читабельной. Однако, когда оказывается, что вам приходится повторять большие фрагменты документации снова и снова, рано или поздно становится выгодным документировать основные аспекты только в одном месте, и ссылаться на него в других местах.