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.
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
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
So if I type
help() and then put in
len and press Enter, then Python prints information about the
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.
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.
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__:
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?
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.
And it must be placed at the top of the function body. So let’s add a docstring to our
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.
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
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.
Become a Member to join the conversation.