Hey guys,
I want to quickly spend a few minutes talking about a concept in Python known as
Docstrings.
Docstrings are basically a way for us to create little bits of documentation as
we're coding along in our functions or in our other blocks of code.
Now, previously, we've seen that when we use other functions
like the ones that were ready to find by Python, like the length function,
you can see that as soon as I open up my parentheses,
I can see this little piece of documentation that tells me what this function is
actually going to do, namely return the number of items in a container.
So how can we create the same kind of documentation for the functions that we
write? Well, we would do that using docstrings.
The docstring has to go as the first line after the declaration.
So here we've defined the name of our function, the inputs,
and then after the colon, the first indented line will be the docstring.
But that's not it.
You also have to use three of these quotation marks and it's in between these
three quotation marks that you can write your documentation.
We could write something like, well, what is this format_
name function going to do?
What would we want our future selves or another user who's using this function
to know about it? Well,
it's going to take a first and last name and format,
it.
Notice how with docstrings
you can actually write strings that are multi-line. Normally,
if I was to create a normal string, let's say, I dunno,
a = "A String".
If I hit the enter key,
I'm going to get a warning because it's going to interpret this as the end of
this line.
And it won't see this closing quotation mark as being a part of this string.
But when we use a docstring, we can write as many lines as we want
and it will be interpreted all as the same thing altogether,
as if it was fitted onto the same line like this.
Now that we've added our docstring, it's time to see what it looks like. Now,
if I call this function format_name, and I open up the parentheses,
you can see that the text we wrote here now gets populated in the documentation.
It takes the first and last name and formats it to return the title
case version of the name.
So this is a way for you to be able to start documenting your functions and
giving each function a little bit of an explainer.
Now you can also use this as a multiline comment.
So notice how when we write a comment and we go to the next line
it becomes code again.
Now you can in fact use something like this
where you just comment as many lines as you like
and this will be interpreted as a comment
as long as it's not assigned to anything. So for example,
if I create a variable
then this is now a piece of code. Because it's a little bit confusing
the official Python guidance is actually to avoid multiline comments like this.
What is actually much easier is to just write your multiline comment and then to
highlight all of it and then to hit command + forward slash or control + forward
slash on Windows.
That's a much better way of differentiating the comment from actual pieces of
code.
Have a go at adding docstrings to the other functions that you've created and
see it show up when you call your functions.