Docstrings3:56 with Kenneth Love
Our functions, classes, and methods are amazing but sometimes a name is just not descriptive enough or there are a lot of arguments. Enter docstrings!
Docstrings don't require the triple-quotes, they just have to be a string, but the triple-quotes let you have newlines in the strings, a very useful formatting feature.
To find out more abrut docstrings, read PEP 257.
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.string. 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
You need to sign up for Treehouse in order to download course files.Sign up