-1

When authoring OOP code, sometimes you have a file that only contains one class, and nothing else.

PEP8 says that all modules and all classes should have docstrings outlining what they do. But in this case, the module is simply a container for the class. If you put a description of the class, then the information is duplicated:

"""
Contains a class for connecting to and communicating with a server.
"""

class Client:
    """
    Class for connecting to and communicating with a server.
    """
    def __init__(self):
        ...

So what should go in the docstrings? Perhaps the module docstring should say Contains Foo or something similar?

  • 1
    Could someone tell me why this is being downvoted? – Omegastick Oct 22 '18 at 9:36
  • It might be because your opening claim is categorically false: it really only applies to Java and has little to do with OOP. P.S. I did not downvote and think your question is actually fine. – Matt Messersmith Oct 22 '18 at 16:40
  • @MattMessersmith I edited the opening statement to be more accurate. – Omegastick Oct 23 '18 at 2:16
1

When authoring OOP code, it is very common to have a file that only contains one class, and nothing else.

This is common in some languages, and may be enforced, like in Java. However, it has very little to do with OOP and more to do with the fact that Java is a popular OOP language. I write/modify several classes in a single file every day (I'm a Python dev), it's a pretty common practice.

PEP8 says that all modules and all classes should have docstrings outlining what they do. But in this case, the module is simply a container for the class. If you put a description of the class, then the information is duplicated

Yes it would be duplicated if you're following a one class per file rule. You have some choices:

  1. Stop following the rule and allow multiple classes per file (especially if you're only following it because it is a perceived best practice)

  2. Just put the docstring in the class and forget the module level docstring. If it's only one class per module (and you strictly follow OOP), then everything will be in the class, so the module docstring will be fairly meaningless. It's perfectly okay to not follow PEP8 to the letter, and in general, it's better to just do what's best for your particular situation than blindly/dogmatically following a standard or best practice.

HTH.

P.S. If a linter is complaining, and this in turn is ruining your builds, there's usually options to turn off certain PEP8 requirements. For example, ignoring E501 (line length greater than 80 chars) is a common one I see that teams choose to ignore (if the pep8 module is your linter, you can do pep8 --ignore=E501, for instance)

  • Maybe the fact that I tend to have one class per file is telling of some other problem in my project. Typically for me, classes are either too long to put more than one in a file reasonably or separated enough from the rest of the project that they wouldn't fit in any other file. If I broke the large classes down a bit and grouped the smaller, separated ones into a 'utils' module then perhaps that would be better. – Omegastick Oct 23 '18 at 2:01
1

Style guides like PEP-8 are not absolute laws that must be followed, but only guides:

However, know when to be inconsistent -- sometimes style guide recommendations just aren't applicable. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!

— PEP 8

Where a module only contains one class, a module-level docstring is not helpful and you should probably leave it out. If you use a linter that requires this superfluous docstring, disable that linter policy for the current file.

If we read PEP-8 more closely, it recommends “docstrings for all public modules”. A module that only contains one class is usually not part of the public interface, you would instead re-export the class through an __init__.py file. Nevertheless, one class per module layouts are fairly rare in Python. You will likely have non-public helper functions or other closely related classes in the same file.

  • Good call on pointing out that PEP8 itself recommends not dogmatically following PEP8. – Matt Messersmith Oct 22 '18 at 16:46

Your Answer

By clicking "Post Your Answer", you agree to our terms of service, privacy policy and cookie policy

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