Should docs of extended methods include documentation of the base method?

Question

Let's say some method of a parent class is reimplemented in a child class.

This child method is intended to do the same that the parent method, with a minor change.

In this case, in the documentation of the child method, is it useful to cover what the parent method do ?

• If we do, the child method is 'self-supporting' but the parent method can be changed and the child doc becomes outdated, or even false

• If we don't, we have to navigate from child to parents to get the full-picture, which can be annoying

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 """ 

Apart from your opinions and preferences (that I would love to hear), do we have 'canonical' sources such as reputable books about this question ?

Edit: I see that by including dumb implementation in the examples above, I made the question confuse by letting think that the documentation was about the implementation details. It is not, so let's remove the implementation. I think the problem still stands with its pros and cons (doc duplication being potentially harmful as code duplication vs. self supporting doc)

Answer 1

Lets stick to your example: the docstring in the child class could be either

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

or

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

Both styles have they pros and cons. The first one has the advantage that a reader has only to look in one place for understanding what a method does. However, it has the drawback that when you change the behaviour in the child class, you might have to change the documentation now in two places - the doc is not DRY any more.

For the second one, it is exactly the opposite: for the reader, it is a disadvantage, but for your maintenance it is an advantage.

Choosing between these two approaches is often a judgement call. A certain amount of redundancy in documentation is certainly ok and helps to keep things more readable. However, when is turns out you have to repeat larger pieces of docs over and over again, sooner or later it will become beneficial when you document central aspects in only one place, and reference that from other places.

Answer 2

Your method does something. Document that. How it does that, whether it calls another method or not, whether that method is its own supermethod or not, is nobody's business.

Document what your method achieves, not how it is implemented.

Answer 3

The main problem here is that seemingly you don't specify some_method's contract, but only its implementations (guessing from the text in the documentation strings).

And that means that you break the abstraction level that you introduced with the method. If your method caller wants to understand its purpose, there's no documentation based on a higher-level abstraction, but only on a list of instructions.

Documentation should primarily describe the contract, not the way the contract is fulfilled inside the method. So, the contract description should be the same for all the relevant methods, the parent method as well as all overriding child methods. Otherwise, it's wrong to override.

Now, which way to go?

• If your example doc strings are taken as the specification what some_method's contract is, then the child method is wrong, as it violates that contract, in doing more than asked for.

• Probably, you have a contract in mind what some_method has to do, valid for all implementations. Then use that contract as the documentation, not the list of implementation steps. And there's no need to change the documentation for the overriding method - the base documentation still applies. Many IDEs and languages allow you to just omit the child method documentation and automatically see the parent doc instead.

• If you really feel it's necessary for a caller of some_method to see that, when used on the Child class, some aspect C is taken care of while fulfilling the contract, document both: a copy of the contract (or a link to the parent documentation, if that's supported) plus a sentence (declared as implementation detail) about C.

Answer 4

There are cases where I don’t care about any class hierarchy. If I show a Button on the screen I care that it is a button, not what it’s base class is. And I would like goto have documentation that the typical user of a button object wants.

So I would look at what users of my class instances often want and document that so that usually reading the documentation of that class is enough.

Answer 5

This very much depends on context. Will the reader of the documentation know/care about the base class and its working?

For example, if this documentation is intended for developers who need active knowledge of the base class and its derived classes, it suffices to refer them back to the base class' workings. Something along the lines of:

Extends Parent.some_method to also do C 

However, there are cases where the reader of your documentation is not aware of the base class, and therefore this documentation wouldn't cut it.

For example, if you're creating a library and you've found some way to introduce reusability (using inheritance in this case) which is not apparent to the public contract of your library (or, alternatively, the reusable part isn't of value to the consumer), then you cannot expect your consumers to be aware of the base class nor its workings.

In that case, the comment should explain the entirety of the behavior:

Does A, B, and C 

When in doubt, favor the latter option.