Function Docstrings

00:00 Now that you’ve seen the variety of ways that you can provide an interface to using your function, let’s talk about other ways that you can communicate to other programmers how your function is supposed to be used.

00:13 It’s considered good programming practice to provide documentation to other programmers on how to use your function: Information about what the function does, what it returns, if anything, and what parameters, if any, that it needs.

00:28 You’ll also find it useful yourself for when you come back and visit a project. Having good documentation will remind you what it was you were thinking when you wrote those functions.

00:40 Python provides function documentation through what it calls a docstring. A docstring is created when the first line under a function’s header is a string literal.

00:54 For example, here is a simple function to find the average of a collection of parameters. It’s included a docstring. It says """Returns the average of a list of numeric values.""" Typically, we use triple quotes (""") using double quotation marks to write this string literal.

01:17 If the documentation fits on a single line, we begin and end with the triple quotes on that same line. On the other hand, if you use a multi-line string for your documentation, then the first part of the string appears on the first line under the function header, but then the docstring is closed with the triple quotes on a line by itself.

01:44 Here is another generic function called foo(). It takes two parameters. We have a description that this performs a foo transformation, where bar represents the magnitude along one axis and baz represents the change of magnitude along the other axis. So again, a string literal, which conventionally we use three double quotes to begin.

02:11 avg()’s docstring fits on a single line, so the ending triple quotes are on the same line. On the other hand, foo()’s docstring is much longer, and so we have the closing quotes on a line by itself.

02:29 Notice where this documentation appears. Many Python editing programs will provide you the documentation when it sees you using that function name, and so we see this popup window showing the docstring for foo() just as we’ve typed it.

02:48 And here’s the docstring for avg() (average).

02:55 Additional ways to view the docstring: We can refer to its attribute __doc__. That is a dunder attribute, an attribute that begins and ends with two double underscores (__).

03:12 And so within our program, or here in our REPL, we can say print() and then the name of the function, and then its dunder attribute __doc__,

03:25 and it shows up that way. While running Python, you can also use help(), followed by the name of the function,

03:35 and depending on how your program displays help()—this provides a separate window—but your documentation is shown that way.

03:49 There are many styles to docstrings. Which one you use can depend on a number of factors. If you’re involved with an existing project, it would be best to match the style that they use to create consistency throughout the project. For your own work, find one that suits you best.

04:09 Look at the different styles that are around and pick the one that seems to match how you like things presented when you’re viewing them.

04:18 Next, we’ll take a look at another way to document your function’s interface, and that’s through annotations.