Documenting Your Functions

00:00 When you create your own functions, you should always document what they do. That way, other developers can read the documentation to know how to use the functions and what to expect from them.

00:13 So let’s hop back to the IDLE editor and explore documentation a little bit. On the right side, I am still having open the functions_and_loops.py file, where we have the shout_and_return() function.

00:28 And on the left side, I have a Python shell. We’ll work in the right file in a second, but for now, let’s go to the Python shell. To get help with a function in IDLE’s interactive window in the Python shell, you can use the help() function.

00:47 So if I type help() and then put in len and press Enter, then Python prints information about the len() function.

00:59 In this case, help() tells you that len() is a built-in function that returns the number of items in a container. Container is a special name for an object that contains other objects.

01:12 So a string is a container because it contains characters. Okay, let’s move to the right side and call the help() function with our shout_and_return function as argument.

01:30 Save it and run it and see what Python tells us.

01:37 Hmm, okay, HELLO was printed because we still have the shout_and_return() function call in line 6, and then it says Help on function shout_and_return in module __main__: shout_and_return(input_string).

01:50 That’s a bit disappointing. If you look at the len() function above, there’s actually information about the function there, but not for us. Do you remember what I said at the end of the last lesson?

02:08 Our function is missing one last detail, the documentation. To document shout_and_return(), you need to provide a so-called docstring.

02:19 A docstring is a triple-quoted string literal placed at the top of the function body. You heard right: a string that is not single-quoted, not double-quoted, but triple-quoted.

02:31 And it must be placed at the top of the function body. So let’s add a docstring to our shout_and_return() function.

02:40 Move to the top of our function body

02:44 and start a docstring with three quotes, and then describe what our function does. Our function prints and returns a string in uppercase. And then you close the docstring with triple quotes as well. Let’s save it and run it again.

03:12 How cool is that? So since we still have the help() function call in line 9, you see the output of help() on the left side. So now you see the docstring prints and returns the string in uppercase as a result of the help() function.

03:29 And that’s all because of the docstring. Docstrings are used to document what a function does and what kind of parameters it expects. You can even spread the docstring over multiple lines, but for smaller functions like this, try to keep the docstring short and sweet and in one line. If you want to learn more about docstrings, I will point you to an additional resource at the end of this course. There, you will learn a bunch more nitty-gritty details about docstrings.

04:00 But now I want to point you to the next lesson, where we will get into the second big topic of this course. So far, we tackled functions in Python. Next, we’ll talk about loops. See you in the next lesson.