Should I include parent's attributes in child class docstring

Python Help
1 
class Parent:
    """
    Class description

    Attributes:
        parent_attr: attribute description
    """

    def __init__(self):
        self.parent_attr = 0


class Child(Parent):
    """
    Class description

    Attributes:
        parent_attr: Should it be included here???
        child_attr: attribute description
    """

    def __init__(self):
        self.child_attr = 1
        super().__init__()

Should I duplicate parent_attr documentation in the Child class?

2

Hello,

from:

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.

If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences. Use the verb “override” to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb “extend” to indicate that a subclass method calls the superclass method (in addition to its own behavior).
3

Does it mean that I should only include parent’s attribute if its behavior in subclass differs from superclass?

4

Yes. If an attribute from a superclass differs and is distinct from one in a subclass, that would be the purpose of inheritance which is what happens when you are subclassing a class. But with respect to docstrings, which is the purpose of your post, read the second paragraph from the PEP above as to how to document it should you choose to. Note that it is not mandatory; it is optional. It is after all your code.

1 Like