1 00:00:05,279 --> 00:00:08,480 Alright, so let's talk about writing a Docstring. 2 00:00:08,480 --> 00:00:12,160 Alright, so I've got guessinggame.py open. We're going to add a Docstring 3 00:00:12,160 --> 00:00:16,820 to our get integer function. Now most modern IDEs will help with this. 4 00:00:16,820 --> 00:00:20,660 I'm using IntelliJ IDEA, and it's got a neat feature that'll generate a 5 00:00:20,660 --> 00:00:24,160 Docstring stub for you. So to do that we need to 6 00:00:24,160 --> 00:00:27,439 create an empty line - start a new line - immediately after the 7 00:00:27,439 --> 00:00:31,279 function definition. So that's on line five here. We need to 8 00:00:31,279 --> 00:00:36,320 type in three double quotes. IntelliJ will add the closing ones for you 9 00:00:36,320 --> 00:00:39,920 and you saw it do that. So without moving the cursor, so that 10 00:00:39,920 --> 00:00:44,960 it's still inside the triple quotes, press enter. IntelliJ detects the 11 00:00:44,960 --> 00:00:49,120 function parameters, and creates this basic stub. Some 12 00:00:49,120 --> 00:00:53,440 companies use a slightly different form, for describing the function parameters. 13 00:00:53,440 --> 00:00:56,000 In that case, they'll modify the Docstring template 14 00:00:56,000 --> 00:00:59,039 for their IDE. So you may get something slightly 15 00:00:59,039 --> 00:01:01,680 different produced, but the basic information 16 00:01:01,680 --> 00:01:05,438 should be the same. Google, for example, use a heading 17 00:01:05,438 --> 00:01:09,200 for the Args and Returns section of the Docstring. 18 00:01:09,200 --> 00:01:12,320 Now I've changed intelliJ to create Google style Docstrings, 19 00:01:12,320 --> 00:01:15,520 but don't change your code to match. I've done that just so you can see the 20 00:01:15,520 --> 00:01:19,280 difference. So I'm going to open up another file now - 21 00:01:19,280 --> 00:01:24,640 example docstring formats, which I've added to the project. 22 00:01:25,200 --> 00:01:28,240 Now don't try to type in this code - it's just an example 23 00:01:28,240 --> 00:01:32,079 of two different ways to format your Docstrings. The first function, 24 00:01:32,079 --> 00:01:35,759 dnd accept, uses restructured text format. 25 00:01:35,759 --> 00:01:38,880 That's the default format that IntelliJ and Pycharm 26 00:01:38,880 --> 00:01:43,759 generate for you. The second function, as I scroll down, 27 00:01:43,840 --> 00:01:47,200 uses Google's convention for Docstrings. So pause the video, 28 00:01:47,200 --> 00:01:51,520 if you want time to examine the two different conventions. 29 00:01:51,759 --> 00:01:55,840 Now if i swing over to a browser, you can check out Google's Python Style Guide 30 00:01:55,840 --> 00:02:00,159 if you wish. The link, as always, is in the resources section of this video. 31 00:02:00,159 --> 00:02:04,479 Alright, so going back to our code, to our guessing game. 32 00:02:04,479 --> 00:02:08,560 Now I'm going to use restructured text Docstrings in this course. 33 00:02:08,560 --> 00:02:12,640 That's the format IntelliJ defaults to. To change the format, 34 00:02:12,640 --> 00:02:17,280 come up here and go into settings - and that's preferences on a Mac. 35 00:02:17,840 --> 00:02:22,879 Once you're in there, come down here to tools and select Python Integrated Tools, 36 00:02:22,879 --> 00:02:27,200 and over here on the right hand side, I'm going to use, or select, restructured text 37 00:02:27,200 --> 00:02:33,920 for the Docstring format. So now you know how to select different formats for your Docstrings. 38 00:02:33,920 --> 00:02:39,300 I'm back in our code, I'm going to delete that Docstring. 39 00:02:39,360 --> 00:02:42,720 I'm going to go over and create it again. 40 00:02:43,920 --> 00:02:47,120 This time you can see we've got a different format. I'm going to start now, 41 00:02:47,120 --> 00:02:51,840 with a one-line description of what the function will do. 42 00:02:59,680 --> 00:03:02,720 So that's a concise description of what this function will do 43 00:03:02,720 --> 00:03:08,080 stdin is the standard input on unix-like systems and the windows command prompt. 44 00:03:08,080 --> 00:03:11,920 Note that we don't mention the keyboard. Input often comes from the keyboard, 45 00:03:11,920 --> 00:03:15,599 but it can come from a file. Google for something like redirect 46 00:03:15,599 --> 00:03:19,760 stdin on windows, if you want to find out more about that. 47 00:03:19,760 --> 00:03:23,760 So the first line is a short descriptive comment, explaining what our function is 48 00:03:23,760 --> 00:03:26,480 for - its purpose, in other words. It doesn't go 49 00:03:26,480 --> 00:03:29,760 into detail about how it does it. So I'm following the 50 00:03:29,760 --> 00:03:33,920 conventions in PEP 257 here. They state that the first line should be 51 00:03:33,920 --> 00:03:38,560 phrased as a command. I've used get there. Google's guidelines 52 00:03:38,560 --> 00:03:42,239 differ here. They state that this line should be descriptive style - in other 53 00:03:42,239 --> 00:03:45,920 words, you'd write Gets an integer from Standard Input. 54 00:03:45,920 --> 00:03:49,599 So let's change that. When you join a company you'll read 55 00:03:49,599 --> 00:03:53,760 and follow their style guide. I'm sticking to PEP 8, which redirects to 56 00:03:53,760 --> 00:03:59,599 PEP 257 for Docstring conventions, so I'm going to undo that change. 57 00:03:59,760 --> 00:04:03,439 Alright, is there anything we can add to that? Well our function keeps 58 00:04:03,439 --> 00:04:06,959 looping until a valid integer is entered. That's worth mentioning. 59 00:04:06,959 --> 00:04:10,560 Anyone calling this function will want to know that it won't exit without a 60 00:04:10,560 --> 00:04:15,840 valid integer. So let's add that. 61 00:04:32,000 --> 00:04:34,800 Alright, so that's a pretty good Docstring. We've given a summary of what 62 00:04:34,800 --> 00:04:37,600 the function's for and provided a brief description 63 00:04:37,600 --> 00:04:41,840 of its behavior. And you've also had a chance, now, to use the backtick character 64 00:04:41,840 --> 00:04:44,639 on your keyboard, probably for the first time ever. You 65 00:04:44,639 --> 00:04:48,080 should be able to find it easily - it'll be one of the few keys on your 66 00:04:48,080 --> 00:04:52,320 keyboard that's still clean and shiny. I've referred to a standard, English 67 00:04:52,320 --> 00:04:55,759 language keyboard here. If you're using a Scandinavian keyboard, 68 00:04:55,759 --> 00:04:58,320 to give one example, then you probably won't have a single 69 00:04:58,320 --> 00:05:02,479 key that produces a back tick character. Search for something like backtick on 70 00:05:02,479 --> 00:05:05,440 swedish keyboard, to find out how you can type one, 71 00:05:05,440 --> 00:05:09,039 if your keyboard doesn't have it. And if you can't type one, 72 00:05:09,039 --> 00:05:12,560 then just ignore it. You can produce perfectly good documentation without 73 00:05:12,560 --> 00:05:15,840 using backticks. We'll see what they do soon, when we 74 00:05:15,840 --> 00:05:18,800 view the documentation that we're producing. 75 00:05:18,800 --> 00:05:21,919 In my code, the backtick appears either side of int, 76 00:05:21,919 --> 00:05:26,720 on line nine. Alright, so next, we document the parameters and return value. 77 00:05:26,720 --> 00:05:30,240 We've only got one parameter, which is a string that'll appear when the user's 78 00:05:30,240 --> 00:05:33,440 prompted. So put a blank line there, and I'm going 79 00:05:33,440 --> 00:05:42,600 add some text here after prompt, and we'll say The String that the user will see, 80 00:05:42,639 --> 00:05:50,080 when they're prompted to enter the value. 81 00:05:50,480 --> 00:05:54,120 You can see that the text on line 11 extends over two lines, 82 00:05:54,120 --> 00:05:57,759 and we use normal indentation to indicate that line 12 is a 83 00:05:57,759 --> 00:06:01,120 continuation of line 11. The documentation will look the same 84 00:06:01,120 --> 00:06:04,800 without that indentation, but it makes the text easier to read. 85 00:06:04,800 --> 00:06:08,800 Not all programmers use Ctrl-Q to check the documentation. Some will just jump 86 00:06:08,800 --> 00:06:12,240 into your source code, as we did with control click. 87 00:06:12,240 --> 00:06:14,880 The indentation helps to separate line 12 from the 88 00:06:14,880 --> 00:06:20,020 return value on line 13. Alright, so the last thing we need to do now 89 00:06:20,020 --> 00:06:24,400 is document the return value. So our function returns an int. So let's 90 00:06:24,400 --> 00:06:32,080 put some documentation there. so it's The integer that the user enters. 91 00:06:33,600 --> 00:06:37,360 Alright, so that's our Docstring finished. Notice that there's no blank 92 00:06:37,360 --> 00:06:40,560 line between the end of triple quotes on line 14, 93 00:06:40,560 --> 00:06:45,140 and the start of the code on line 15. That took a lot longer to explain than 94 00:06:45,140 --> 00:06:49,599 it would normally take you to type, and our function is now documented. If you 95 00:06:49,599 --> 00:06:51,680 want to use this function in a year's time, 96 00:06:51,680 --> 00:06:55,919 you can quickly see what it does. So let's do that. 97 00:06:55,919 --> 00:06:59,759 I'll click on get_integer on line 30. 98 00:06:59,759 --> 00:07:04,800 On a mac you can use Ctrl_J. I'm using windows, so Ctrl-Q 99 00:07:04,800 --> 00:07:07,599 has brought up the documentation, as you can see. So how cool is that? It's just 100 00:07:07,599 --> 00:07:10,319 like a bought one. Our function now provides proper 101 00:07:10,319 --> 00:07:13,840 documentation on what it does, and how to use it. It just looks so 102 00:07:13,840 --> 00:07:16,720 professional. Another thing you can do also, is you can 103 00:07:16,720 --> 00:07:20,960 just hover over it. That also brings up the documentation 104 00:07:20,960 --> 00:07:24,520 Alright, so in the next video, I'll discuss what we've produced. 105 00:07:24,520 --> 00:07:30,180 Before then, I'll finish this video with two home truths. 106 00:07:45,919 --> 00:07:52,000 See you in the next video.