WEBVTT 0 00:00.080 --> 00:07.010 Hey guys, I want to quickly spend a few minutes talking about a concept in Python known as Docstrings. 1 00:07.130 --> 00:13.790 Docstrings are basically a way for us to create little bits of documentation as we're coding along 2 00:13.790 --> 00:17.000 in our functions, or in our other blocks of code. 3 00:17.150 --> 00:22.970 Now, previously we've seen that when we use other functions, like the ones that were already defined 4 00:22.970 --> 00:29.960 by Python, like the len() function, I can see this little piece of documentation that tells me what 5 00:29.960 --> 00:35.220 this function is actually going to do, namely, "Return the number of items in a container." 6 00:35.250 --> 00:40.650 So how can we create the same kind of documentation for the functions that we write? 7 00:40.680 --> 00:43.320 Well, we would do that using docstrings. 8 00:43.320 --> 00:48.270 The docstring has to go as the first line after the declaration. 9 00:48.270 --> 00:52.230 So here we've defined the name of our function the inputs. 10 00:52.230 --> 00:57.150 And then after the colon the first indented line will be the docstring. 11 00:57.150 --> 00:58.150 But that's not it, 12 00:58.150 --> 01:06.280 you also have to use three of these quotation marks, and it's in between these three quotation marks 13 01:06.280 --> 01:08.290 that you can write your documentation. 14 01:08.830 --> 01:12.790 We could write something like, well, what is this format name function going to do? 15 01:12.820 --> 01:18.760 What would we want our future selves or another user who's using this function to know about it? 16 01:18.790 --> 01:26.240 Well, it's going to """Take a first and last name and format it...""" 17 01:29.510 --> 01:35.090 Notice how with docstrings you can actually write strings that are multi-line. 18 01:35.120 --> 01:41.330 Normally, if I was to create a normal string, let's say I don't know, a = ("A string 19 01:42.680 --> 01:48.350 ") If I hit the Enter key, I'm going to get a warning because it's going to interpret this as the end of 20 01:48.350 --> 01:54.900 this line and it won't see this closing quotation mark as being a part of this string. 21 01:54.900 --> 02:01.800 But when we use a docstring, we can write as many lines as we want, and it will be interpreted all 22 02:01.800 --> 02:06.750 as the same thing all together, as if it was fitted onto the same line, 23 02:06.750 --> 02:07.950 like this. 24 02:08.760 --> 02:13.470 Now that we've added our docstring, it's time to see what it looks like. 25 02:13.470 --> 02:21.050 Now, if I call this function, you can see that the text we wrote here now gets populated in the documentation. 26 02:21.050 --> 02:26.540 "It takes the first and last name and formats it to return the title case version of the name." 27 02:27.110 --> 02:32.840 So this is a way for you to be able to start documenting your functions and giving each function a little 28 02:32.840 --> 02:34.460 bit of an explainer. 29 02:34.520 --> 02:39.950 Now you can also use this as a multi-line comment. 30 02:39.950 --> 02:44.850 So notice how when we write a comment and we go to the next line, it becomes code again. 31 02:44.880 --> 02:53.730 Now you can, in fact, use something like this where you just comment as many lines as you like and this 32 02:53.730 --> 02:58.410 will be interpreted as a comment as long as it's not assigned to anything. 33 02:58.410 --> 03:04.110 So for example, if I create a variable, then this is now a piece of code. Because it's a little bit 34 03:04.110 --> 03:05.040 confusing, 35 03:05.040 --> 03:09.460 the official Python guidance is actually to avoid multi-line comments like this. 36 03:09.490 --> 03:16.540 What is actually much easier is to just write your multi-line comment, and then to highlight all of 37 03:16.540 --> 03:21.370 it, and then to hit cmd + / or Ctrl + / on windows. 38 03:21.460 --> 03:26.620 That's a much better way of differentiating the comment from actual pieces of code. 39 03:27.280 --> 03:33.400 Have a go at adding docstrings to the other functions that you've created, and see it show up when 40 03:33.400 --> 03:34.990 you call your functions.