Python Docstring: Documenting Your Code

A python docstring allows you to document your code more formally. We’ll first look at what a docstring is exactly. Next, we’ll create our own docstrings. Finally, I’ll show you how to read docstrings.

What is a Python docstring?

Let’s start by defining what a docstring is. This is taken straight from PEP-0257, which introduces docstrings:

Docstring

A docstring is a string that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the __doc__ special attribute of that object.

There’s a clear distinction between Python comments and docstrings. A comment is ignored completely by the Python interpreter, while a docstring is an actual string that the interpreter sees. Because we don’t assign the string, it’s considered useless by the interpreter while running the code and is effectively ignored. So the effect of a docstring, in short, is the same: it’s a piece of text that documents your code.

However, there’s still an essential difference between comments and docstrings, because Python can actually find and show the docstring when asked for, since it gets assigned to the __doc__ special attribute. It can be used as a way to formally document your code, as you’ll soon learn.

How to create Python docstrings

As defined above, we can simply insert a string as the first statement of any module, function, class, or method and it becomes the docstring. Here’s an example of how to document a Python class and its functions using docstrings:

class MyDocumentedClass:
    """This class is well documented but doesn't do anything special."""

    def do_nothing(self):
        """This method doesn't do anything but feel free to call it anyway."""
        pass

As you can see, I created these strings with triple quotes. It’s for a reason: they are more recognizable as a docstring, and it’s easier to expand them to multi-line strings later on (if needed).

How to read docstrings

The docstring is internally assigned to the __doc__ special attribute. Usually, you don’t access it that way, though. Instead, we call help(MyDocumentedClass) in a Python REPL to see the result of these docstrings:

Help on class MyDocumentedClass in module __main__:

class MyDocumentedClass(builtins.object)
 |  This class is well documented but doesn't do anything special
 |
 |  Methods defined here:
 |
 |  do_nothing(self)
 |      This method doesn't do anything but feel free to call it anyway

Here’s an interactive example of the same class to experiment with this yourself:

You can use help on any object in Python. I encourage you to try this. E.g., enter help(print) to get the docstring from the print function, or help(str) to view the string class with all its useful methods. You can also ask for the documentation of methods within a class, e.g. with help(str.title) you can learn what the title() method on a string object does.

Keep learning

• Docstrings were proposed and described in detail in PEP-0257
• Python comments are used to further document and explain your code