1

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)

1
  • Better rename to some_method_with_extra_c ( ) as it is no longer an override. It would have been an override if child method still did A and B but in a different way internally.
    – S.D.
    Commented Aug 9, 2022 at 14:09

5 Answers 5

0

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.

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.

2
  • In case the child method does the same than the parent method, with a small detail changed, don't you fear that the documentation becomes excessively redundant ?
    – NonoG
    Commented Jul 29, 2022 at 16:39
  • @NonoG If two methods do similar but slightly different things (whether they are separate methods or overridden methods), the documentation might overlap some, yes. But as long as you stick to documenting the what (and why, in some cases) of your method, and not the how, as the answer indicates, that overlap is fine.
    – mmathis
    Commented Jul 29, 2022 at 18:04
1

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.

0

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.

0

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.