1 00:00:05,359 --> 00:00:08,480 Our get integer function is now looking very professional. 2 00:00:08,480 --> 00:00:12,400 It's got a Docstring that tools such as IntelliJ and Pycharm, 3 00:00:12,400 --> 00:00:15,440 can use to provide documentation about the function. 4 00:00:15,440 --> 00:00:18,560 I'll call up the function again - come down to line 30 - 5 00:00:18,560 --> 00:00:23,300 and I'll just hover over the get_integer function to see the documentation. 6 00:00:23,300 --> 00:00:25,040 Alternatively, as I've said a few times now, 7 00:00:25,040 --> 00:00:29,439 you can also use control Q. So at the very top we have the module 8 00:00:29,439 --> 00:00:33,440 that the function comes from. We created get integer in our guessing 9 00:00:33,440 --> 00:00:37,920 game program, so that's the module. That's a clickable link, by the way. If we 10 00:00:37,920 --> 00:00:40,879 wanted to view the source code, you can click guessinggame at the top of the 11 00:00:40,880 --> 00:00:44,360 documentation, and jump directly to that module. 12 00:00:44,360 --> 00:00:49,100 I won't do that here because we've already got the module open in the editor. 13 00:01:17,540 --> 00:01:20,479 So below that, in our documentation, is 14 00:01:20,479 --> 00:01:24,960 the text from our function's Docstring. Notice that the word int appears 15 00:01:24,960 --> 00:01:28,640 slightly differently, from the rest of the text. When you 16 00:01:28,640 --> 00:01:32,340 enclose a name in backticks, it gets formatted differently. Single 17 00:01:32,340 --> 00:01:35,759 Single backticks, like we used in our docstring for int, 18 00:01:35,759 --> 00:01:38,320 represent something that's the name of a variable, 19 00:01:38,320 --> 00:01:43,040 function or class. If you can't type back ticks on your keyboard, it's not the end 20 00:01:43,040 --> 00:01:45,680 of the world. You just wouldn't get that font change 21 00:01:45,680 --> 00:01:49,420 in your documentation. But if you can type it, then use backticks 22 00:01:49,420 --> 00:01:54,240 around the names of anything that you refer to. So continuing on down, 23 00:01:54,240 --> 00:01:59,119 next we have the params section. Notice that the word Params 24 00:01:59,119 --> 00:02:02,799 appears in grey, and that the following text is indented. 25 00:02:02,799 --> 00:02:06,640 That's all done automatically, and the same happens for the Returns 26 00:02:06,640 --> 00:02:10,318 text as well. We don't have to worry about formatting our text. 27 00:02:10,318 --> 00:02:13,840 The doc utils tool took care of all of that for you. 28 00:02:13,840 --> 00:02:17,120 More accurately, theRestructuredText formatting 29 00:02:17,120 --> 00:02:20,480 takes care of all that for us. It's inserted the em dash 30 00:02:20,480 --> 00:02:24,800 after prompt in the Params section. It took care of the different font 31 00:02:24,800 --> 00:02:30,400 for int. 32 00:02:57,360 --> 00:03:01,480 And what I'll do specifically is add a couple of lines of code after our function definition, 33 00:03:01,480 --> 00:03:04,000 leaving two blank lines after the function. 34 00:03:04,000 --> 00:03:07,920 So let's go and have a look at that, back up here. 35 00:03:07,920 --> 00:03:11,120 So I'm going to start coding on line 23. 36 00:03:11,120 --> 00:03:18,159 So I type in print parentheses input dot underscore underscore doc 37 00:03:18,159 --> 00:03:24,319 underscore underscore. Next line, print parentheses double quotes 38 00:03:24,320 --> 00:03:26,400 and I'm going to put a star in double quotes, 39 00:03:26,400 --> 00:03:31,960 then multiplied by 80. We get a line of asterisks across the output. 40 00:03:31,960 --> 00:03:34,879 I'm going to type print parentheses 41 00:03:34,879 --> 00:03:39,120 get_integer dot then underscore underscore doc 42 00:03:39,120 --> 00:03:42,560 underscore underscore, closing right parenthesi, 43 00:03:42,560 --> 00:03:47,760 and take a copy of line 24 and paste it onto line 26. 44 00:03:48,239 --> 00:03:52,720 So we're not calling the functions here - we're referring their attributes. 45 00:03:52,720 --> 00:03:56,080 That means that we don't use parentheses after the function name. 46 00:03:56,080 --> 00:04:01,840 Alright, so let's run the program and we'll check the output. 47 00:04:01,900 --> 00:04:05,519 And if we scroll up and look at our output pane, 48 00:04:05,519 --> 00:04:09,200 the first block might look familiar. That's because it's the Docstring 49 00:04:09,200 --> 00:04:12,400 from the built-in input function, and we looked at that earlier. 50 00:04:12,400 --> 00:04:16,880 After the row of asterisks, we get the Docstring from our get_integer function 51 00:04:16,880 --> 00:04:20,079 You can see that as I scroll down a bit. Now that's not something you'd 52 00:04:20,079 --> 00:04:23,520 normally do. It's much quicker to use Ctrl-Q or hover 53 00:04:23,520 --> 00:04:26,880 over the function name, but it does explain why Docstrings go inside the 54 00:04:26,880 --> 00:04:30,720 function definition, rather than before it. Now something else 55 00:04:30,720 --> 00:04:34,700 you can do to get a similar result, is to use the built-in help. 56 00:04:34,700 --> 00:04:38,640 So what I'm going to do is replace those four lines. 57 00:04:39,759 --> 00:04:46,320 Place those, and we're going to type help parentheses get_integer, 58 00:04:46,320 --> 00:04:51,680 but minus the parentheses again. If you run the program, 59 00:04:52,080 --> 00:04:55,680 you can see we've got the get_integer Docstring printed out again. 60 00:04:55,680 --> 00:04:59,360 That can be useful when you're working in the Python interactive shell, 61 00:04:59,360 --> 00:05:03,280 rather than an IDE. Run help, and pass the name of the Python object 62 00:05:03,280 --> 00:05:07,440 as its argument, and you'll see the Docstring for that object. 63 00:05:07,440 --> 00:05:11,199 Okay, so what I'll do now is guess correctly to terminate the program 64 00:05:11,199 --> 00:05:14,000 and stop the video here. 65 00:05:14,080 --> 00:05:18,000 In the next few videos, we'll actually write some more functions to practise 66 00:05:18,000 --> 00:05:22,080 what we've learnt so far. I wanted to cover Docstrings first, 67 00:05:22,080 --> 00:05:24,000 so that we can write Docstrings for our functions, 68 00:05:24,000 --> 00:05:27,760 moving forward. The way to teach best practice is by example, 69 00:05:27,760 --> 00:05:33,660 and I wanted to set a good example. Alright, so I'll finish now with a challenge. 70 00:05:58,120 --> 00:06:00,640 Now I'm not going to be going through my solution on video. 71 00:06:00,640 --> 00:06:04,000 You can see the Docstrings that we came up with, in the next video, 72 00:06:04,000 --> 00:06:08,560 which is a document showing the code. 73 00:06:08,560 --> 00:06:14,960 See you in the next video.