1 00:00:00,340 --> 00:00:03,820 If you remember all the way back to our first course, Python basics, 2 00:00:03,820 --> 00:00:08,040 one of the first things that I taught you in the Python shell was the Help function. 3 00:00:08,040 --> 00:00:10,540 It's a great way to get help on all the different functions and 4 00:00:10,540 --> 00:00:12,330 methods in the language. 5 00:00:12,330 --> 00:00:14,250 But where does all that help come from? 6 00:00:15,290 --> 00:00:18,120 Well, it actually comes from Python developers just like you and I. 7 00:00:18,120 --> 00:00:19,890 People writing their own software and 8 00:00:19,890 --> 00:00:22,310 including something that Python calls a Docstring. 9 00:00:23,352 --> 00:00:26,730 A docstring is a string at the beginning of a class, method or 10 00:00:26,730 --> 00:00:31,730 function that documents what that little bit of class or function is for. 11 00:00:31,730 --> 00:00:35,160 Let's just jump in to workspaces and see how to add them to our own code. 12 00:00:35,160 --> 00:00:37,910 This is a pretty simple script on its own. 13 00:00:37,910 --> 00:00:42,330 But if you were just given this as a library to use, say, by a coworker that 14 00:00:42,330 --> 00:00:46,220 had created this as a handy solution to a problem that they'd had. 15 00:00:46,220 --> 00:00:50,620 You'd be really hard-pressed to figured out what does something does without 16 00:00:50,620 --> 00:00:51,940 reading the source code. 17 00:00:51,940 --> 00:00:55,440 You should never have to read the code to figure out what a library does. 18 00:00:55,440 --> 00:00:59,331 That's the job of documentation, like ReadMes a full-fledged documentation, 19 00:00:59,331 --> 00:01:00,450 including Docstring. 20 00:01:01,470 --> 00:01:04,028 Okay, that's enough soap boxing, let's actually fix this. 21 00:01:04,028 --> 00:01:07,700 Docstrings are strings. 22 00:01:07,700 --> 00:01:11,810 And they're enclosed in three quote marks often called triple quotes. 23 00:01:11,810 --> 00:01:15,610 So, they can either be single quotes or double quote. 24 00:01:15,610 --> 00:01:17,650 You just have to be consistent for both of them. 25 00:01:17,650 --> 00:01:19,560 So, let's add a docstring to this. 26 00:01:19,560 --> 00:01:21,390 Let's explain what does something does. 27 00:01:21,390 --> 00:01:27,980 So we'll say it takes one argument and do something. 28 00:01:27,980 --> 00:01:32,480 Or does something, based on type. 29 00:01:34,490 --> 00:01:42,190 If arg is a string, returns arg times three. 30 00:01:43,650 --> 00:01:52,257 If arg is a, an int or a float, returns arg plus 10. 31 00:01:52,257 --> 00:01:56,774 [NOISE] Okay. 32 00:01:56,774 --> 00:01:59,330 So we started with three double quotes. 33 00:01:59,330 --> 00:02:00,610 We ended with three double quotes. 34 00:02:00,610 --> 00:02:02,810 And we started on the same line. 35 00:02:02,810 --> 00:02:06,110 So what does writing a docstring give us? 36 00:02:06,110 --> 00:02:08,499 Well, now that we've saved this. 37 00:02:09,600 --> 00:02:11,310 Let's let's come down here into our shell. 38 00:02:12,500 --> 00:02:13,640 And we'll go into Python. 39 00:02:13,640 --> 00:02:14,230 Oops. 40 00:02:14,230 --> 00:02:15,710 Python. 41 00:02:15,710 --> 00:02:19,640 And let's import docstrings. 42 00:02:19,640 --> 00:02:22,930 Which is our library here that we wrote, our file. 43 00:02:22,930 --> 00:02:28,724 And let's ask for help about docstrings.does_something. 44 00:02:30,170 --> 00:02:33,000 So look at that, we get help about this. 45 00:02:33,000 --> 00:02:35,610 It says that it takes one argument and does something based on type. 46 00:02:35,610 --> 00:02:38,340 If arg is a string, returns arg times three. 47 00:02:38,340 --> 00:02:41,530 If arg is an ent or a float, returns arg plus 10. 48 00:02:41,530 --> 00:02:43,600 So awesome, there's our help text. 49 00:02:44,690 --> 00:02:49,110 Now future users of do something will know exactly what it does without having to 50 00:02:49,110 --> 00:02:49,770 read the source code. 51 00:02:49,770 --> 00:02:52,170 They can just pull it in and ask for help. 52 00:02:52,170 --> 00:02:54,260 Like many other things in Python, 53 00:02:54,260 --> 00:02:57,210 docstrings actually have their own PEP which is PEP 257. 54 00:02:57,210 --> 00:03:00,330 It's not one that you have to memorize though. 55 00:03:00,330 --> 00:03:02,310 It has two basic rules. 56 00:03:02,310 --> 00:03:05,330 Docstrings that can fit on one line, should. 57 00:03:05,330 --> 00:03:08,630 And docstrings that can't, put the closing triple quotes on their own line. 58 00:03:08,630 --> 00:03:12,930 You might have noticed that docstrings are considered comments when not assigned to 59 00:03:12,930 --> 00:03:13,950 a variable. 60 00:03:13,950 --> 00:03:14,660 Like this. 61 00:03:14,660 --> 00:03:22,810 If I come in here and do triple quotes then that looks and acts like a comment. 62 00:03:22,810 --> 00:03:25,560 You're gonna be tempted to use these as multi-line comments. 63 00:03:25,560 --> 00:03:28,410 But lots of times that's more confusing than it needs to be. 64 00:03:29,440 --> 00:03:32,740 I recommend just commenting out multiple lines by putting hash marks at 65 00:03:32,740 --> 00:03:34,830 the beginning of multiple lines. 66 00:03:34,830 --> 00:03:38,570 Don't, don't do it as a docstring. 67 00:03:38,570 --> 00:03:42,110 If you need to have a string with new line characters in it, you can use docstrings. 68 00:03:42,110 --> 00:03:45,190 Just assign them to a variable and they act just like any other string. 69 00:03:46,420 --> 00:03:48,500 You've learned a lot about making your code more beautiful. 70 00:03:48,500 --> 00:03:52,100 By doing this, you'll also make your code friendlier to other developers. 71 00:03:52,100 --> 00:03:55,980 Now let's make our code communicate better with us, using the logging library