Docstrings

1. Docstrings

Custom functions, when designed well, can be fairly intuitive. But it's great to make things easy for ourselves and others to understand how to use our functions. With that in mind, let's look at one more important element of custom functions: docstrings.

2. Docstrings

A docstring is a string, or block of text, used to describe what a function does. Docstrings are displayed, along with additional information, when we use the help function. Here, we see the docstring as part of the output of calling help on the round function. Docstrings are incredibly useful as they explain how to use functions.

3. Accessing a docstring

So, we can get information about a function, including its docstring, by calling help.

4. Accessing a docstring

However, if we just want the docstring, then we write the function name,

5. Accessing a docstring

add a dot,

6. Accessing a docstring

then two underscores.

7. Accessing a docstring

We then write doc, representing the docstring,

8. Accessing a docstring

and finish with two more underscores and a closing parenthesis. Two sets of double underscores are referred to as "dunder" in programming. In this case, we access the "dunder-doc" attribute of the round function. The output only shows the docstring without any additional information.

9. Creating a docstring

Let's add a docstring to the average function that we created earlier. To add a docstring, we use triple quotation marks directly after defining the function. Here, we provide a brief description, which is known as a one-line docstring. Just like any other content within the function body, the docstring must be indented.

10. Accessing the docstring

We can display our docstring by accessing the function's dunder-doc attribute as we did before!

11. Updating a docstring

Because dunder-doc is an attribute of a function, we can modify a docstring by assigning a new value to it! Here, we assign the average function's docstring to a new sentence. If we call the `help()` function on our average again, we see the updated docstring.

12. Multi-line docstring

We can also use a multi-line docstring to provide more information, which is useful if the function is more complex or has lots of arguments.

13. Multi-line docstring

We keep the summary line at the start, leave a blank line, and then write Args, representing the function's arguments.

14. Multi-line docstring

We then indent the next line and write the argument name, put its data type in brackets, and add a brief description. We can repeat this if we have more arguments.

15. Multi-line docstring

We then write Returns, and again indent. Here, we describe the variable that is returned, including its data type.

16. Accessing the docstring

Calling help shows our full docstring, including the blank line formatting.

17. Let's practice!

Let's add docstrings to some functions!

Create Your Free Account

By continuing, you accept our Terms of Use, our Privacy Policy and that your data is stored in the USA.