__doc__ is a special attribute that stores a string defining the documentation for a module, class, method, or function. It’s typically derived from a docstring — the first statement in the defined block, enclosed in triple quotes — providing a convenient way to access descriptive texts about the code’s functionality.
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.
This Python code defines a class
Dog with a docstring “Your best friend.” and a method
do_nothing that does nothing (using the
pass statement). The
print(Dog.__doc__) statement then prints the docstring of the
class Dog: This line starts the definition of a class named
"""Your best friend.""": This is a docstring, a special string literal used to document the
Dogclass. It describes what the class represents or does.
def do_nothing(self): This defines a method named
selfparameter refers to the instance of the class on which the method is called.
pass: This is a placeholder statement that does nothing. It’s used here because Python syntax requires at least one statement in the method body, and
do_nothingis intended to be an empty method.
print(Dog.__doc__): This line prints the docstring of the
Dogclass. In Python,
__doc__is a special attribute that holds the docstring of a class, function, method, or module. In this case, it prints
"Your best friend."
The code demonstrates how to define a simple class with a docstring and access that docstring using the
__doc__ attribute. The output of this code will be:
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!
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
def bark(): pass print(bark.__doc__) # None
Why Use 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.
In particular, you can use docstrings in Python to:
- Document functions, classes, and modules directly in the code.
- Enhance code readability and maintainability.
- Standardize documentation for easy access through tools like Sphinx and IDEs.
- Enable runtime introspection of documentation via the
- Facilitate testing by integrating with testing frameworks for descriptive test cases.
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:
- All modules, function, methods, and classes should have docstrings.
- Always use
"""triple double quotes"""around your docstrings for consistency reasons.
- Use triple quotes even if the docstring fits into a single line. This allows for easy expansion later.
- No blank line before or after the docstring—except for classes where you should add one line after the docstring.
- 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.""".
- 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.
- 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.
While working as a researcher in distributed systems, Dr. Christian Mayer found his love for teaching computer science students.
To help students reach higher levels of Python success, he founded the programming education website Finxter.com that has taught exponential skills to millions of coders worldwide. He’s the author of the best-selling programming books Python One-Liners (NoStarch 2020), The Art of Clean Code (NoStarch 2022), and The Book of Dash (NoStarch 2022). Chris also coauthored the Coffee Break Python series of self-published books. He’s a computer science enthusiast, freelancer, and owner of one of the top 10 largest Python blogs worldwide.
His passions are writing, reading, and coding. But his greatest passion is to serve aspiring coders through Finxter and help them to boost their skills. You can join his free email academy here.