What is __ doc __ in Python?

5/5 - (4 votes)

Python objects have an attribute called __doc__ that provides a documentation of the object. For example, you simply call Dog.__doc__ on your class Dog to retrieve its documentation as a string.

What is __ doc __ in Python?

You can define the docstring using a string surrounded by triple quotes as shown in the example:

class Dog:
    """Your best friend."""

    def do_nothing(self):
        pass


print(Dog.__doc__)
# Your best friend. 

Try it yourself in the interactive Python shell:

If you already learned something from this tutorial, why not joining my free Python training program? I call it the Finxter Email Computer Science Academy—and it’s just that: a free, easy-to-use email academy that teaches you Python in small daily doses for beginners and pros alike!

Learn Python and join the Free Finxter Email Computer Science Academy. It’s fun!

Let’s go back to the docstring. As everything is an object in Python (even functions), you can also define a docstring on functions:

def bark():
    """Wuff"""
    pass


print(bark.__doc__)
# Wuff

Note that if you don’t define the docstring, the return value is None.

def bark():
    pass


print(bark.__doc__)
# None

Do you want to develop the skills of a well-rounded Python professional—while getting paid in the process? Become a Python freelancer and order your book Leaving the Rat Race with Python on Amazon (Kindle/Print)!

Leaving the Rat Race with Python Book

Why Using Docstrings?

A great advantage of having defined docstrings in your code is that you now can create your own great-looking documentation programmatically. With tools such as Sphinx, it’s super easy to create something like this for your own code projects–only using the __doc__ values defined in the code.

Best Practices Docstring

There are a couple of best-practices called Docstring Conventions as defined in the official PEP standard. Adhere to them when defining your docstrings. Here are the 7 most important docstring conventions:

  1. All modules, function, methods, and classes should have docstrings.
  2. Always use """triple double quotes""" around your docstrings for consistency reasons.
  3. Use triple quotes even if the docstring fits into a single line. This allows for easy expansion later.
  4. No blank line before or after the docstring—except for classes where you should add one line after the docstring.
  5. Use a phrase that describes what your code is doing such as """Do X and return Y.""" ending in a period. Don’t use a description such as """Does X and returns Y.""".
  6. Multi-line docstrings start with a summary line (like the one-liner docstring), followed by a blank line, followed by a closer description such as argument --- name of the person (string) to describe one of the arguments of the function or method. For example, you can use one line per argument.
  7. Start a multi-line docstring immediately in the same line of the opening """triple double strings... rather than starting the text in a new line.

If you’re a perfectionist or beyond intermediate code level, check out the official documentation that contains more examples.

Where to Go From Here?

Enough theory. Let’s get some practice!

Coders get paid six figures and more because they can solve problems more effectively using machine intelligence and automation.

To become more successful in coding, solve more real problems for real people. That’s how you polish the skills you really need in practice. After all, what’s the use of learning theory that nobody ever needs?

You build high-value coding skills by working on practical coding projects!

Do you want to stop learning with toy projects and focus on practical code projects that earn you money and solve real problems for people?

🚀 If your answer is YES!, consider becoming a Python freelance developer! It’s the best way of approaching the task of improving your Python skills—even if you are a complete beginner.

If you just want to learn about the freelancing opportunity, feel free to watch my free webinar “How to Build Your High-Income Skill Python” and learn how I grew my coding business online and how you can, too—from the comfort of your own home.

Join the free webinar now!

Leave a Comment