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 already defined
by Python, like the len() function, 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 don't know, 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 all together, 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, 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 multi-line 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 multi-line comments like this.
What is actually much easier is to just write your multi-line comment, and then to highlight all of
it, and then to hit cmd + / or Ctrl + / 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.