Preview
Video Player
00:00
00:00
Docstrings
3:56Our functions, classes, and methods are amazing but sometimes a name is just not descriptive enough or there are a lot of arguments. Enter docstrings!
If you remember all the way back to our
first course, Python basics,
0:00
one of the first things that I taught you
in the Python shell was the Help function.
0:03
It's a great way to get help on all the
different functions and
0:08
methods in the language.
0:10
But where does all that help come from?
0:12
Well, it actually comes from Python
developers just like you and I.
0:15
People writing their own software and
0:18
including something that Python calls a
Docstring.
0:19
A docstring is a string at the beginning
of a class, method or
0:23
function that documents what that little
bit of class or function is for.
0:26
Let's just jump in to workspaces and see
how to add them to our own code.
0:31
This is a pretty simple script on its own.
0:35
But if you were just given this as a
library to use, say, by a coworker that
0:37
had created this as a handy solution to a
problem that they'd had.
0:42
You'd be really hard-pressed to figured
out what does something does without
0:46
reading the source code.
0:50
You should never have to read the code to
figure out what a library does.
0:51
That's the job of documentation, like
ReadMes a full-fledged documentation,
0:55
including Docstring.
0:59
Okay, that's enough soap boxing, let's
actually fix this.
1:01
Docstrings are strings.
1:04
And they're enclosed in three quote marks
often called triple quotes.
1:07
So, they can either be single quotes or
double quote.
1:11
You just have to be consistent for both of
them.
1:15
So, let's add a docstring to this.
1:17
Let's explain what does something does.
1:19
So we'll say it takes one argument and do
something.
1:21
Or does something, based on type.
1:27
If arg is a string, returns arg times
three.
1:34
If arg is a, an int or a float, returns
arg plus 10.
1:43
[NOISE]
Okay.
1:52
So we started with three double quotes.
1:56
We ended with three double quotes.
1:59
And we started on the same line.
2:00
So what does writing a docstring give us?
2:02
Well, now that we've saved this.
2:06
Let's let's come down here into our shell.
2:09
And we'll go into Python.
2:12
Oops.
2:13
Python.
2:14
And let's import docstrings.
2:15
Which is our library here that we wrote,
our file.
2:19
And let's ask for help about
docstrings.does_something.
2:22
So look at that, we get help about this.
2:30
It says that it takes one argument and
does something based on type.
2:33
If arg is a string, returns arg times
three.
2:35
If arg is an ent or a float, returns arg
plus 10.
2:38
So awesome, there's our help text.
2:41
Now future users of do something will know
exactly what it does without having to
2:44
read the source code.
2:49
They can just pull it in and ask for help.
2:49
Like many other things in Python,
2:52
docstrings actually have their own PEP
which is PEP 257.
2:54
It's not one that you have to memorize
though.
2:57
It has two basic rules.
3:00
Docstrings that can fit on one line,
should.
3:02
And docstrings that can't, put the closing
triple quotes on their own line.
3:05
You might have noticed that docstrings are
considered comments when not assigned to
3:08
a variable.
3:12
Like this.
3:13
If I come in here and do triple quotes
then that looks and acts like a comment.
3:14
You're gonna be tempted to use these as
multi-line comments.
3:22
But lots of times that's more confusing
than it needs to be.
3:25
I recommend just commenting out multiple
lines by putting hash marks at
3:29
the beginning of multiple lines.
3:32
Don't, don't do it as a docstring.
3:34
If you need to have a string with new line
characters in it, you can use docstrings.
3:38
Just assign them to a variable and they
act just like any other string.
3:42
You've learned a lot about making your
code more beautiful.
3:46
By doing this, you'll also make your code
friendlier to other developers.
3:48
Now let's make our code communicate better
with us, using the logging library
3:52