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. 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.

9. Accessing a docstring

The output shows the same information as the help function, except it has some strange characters, a backslash followed by "n". This is actually code representing a new line, which is why when we compare this to the output of help there are sentences split across separate lines.

10. 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.

11. Accessing the docstring

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

12. 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 average function's docstring to a new sentence.

13. 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.

14. Multi-line docstring

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

15. 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.

16. Multi-line docstring

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

17. Accessing the docstring

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

18. 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.