1
00:00:00,090 --> 00:00:00,780
Hey guys,

2
00:00:00,780 --> 00:00:05,780
I want to quickly spend a few minutes talking about a concept in Python known as

3
00:00:05,939 --> 00:00:06,780
Docstrings.

4
00:00:07,410 --> 00:00:12,410
Docstrings are basically a way for us to create little bits of documentation as

5
00:00:12,780 --> 00:00:16,680
we're coding along in our functions or in our other blocks of code.

6
00:00:17,490 --> 00:00:20,970
Now, previously, we've seen that when we use other functions

7
00:00:20,970 --> 00:00:25,740
like the ones that were ready to find by Python, like the length function,

8
00:00:26,070 --> 00:00:29,310
you can see that as soon as I open up my parentheses,

9
00:00:29,640 --> 00:00:34,170
I can see this little piece of documentation that tells me what this function is

10
00:00:34,170 --> 00:00:38,370
actually going to do, namely return the number of items in a container.

11
00:00:39,000 --> 00:00:43,500
So how can we create the same kind of documentation for the functions that we

12
00:00:43,500 --> 00:00:46,590
write? Well, we would do that using docstrings.

13
00:00:46,980 --> 00:00:51,570
The docstring has to go as the first line after the declaration.

14
00:00:51,900 --> 00:00:55,590
So here we've defined the name of our function, the inputs,

15
00:00:55,800 --> 00:01:00,420
and then after the colon, the first indented line will be the docstring.

16
00:01:00,810 --> 00:01:01,590
But that's not it.

17
00:01:01,590 --> 00:01:06,590
You also have to use three of these quotation marks and it's in between these

18
00:01:08,460 --> 00:01:11,550
three quotation marks that you can write your documentation.

19
00:01:12,510 --> 00:01:14,820
We could write something like, well, what is this format_

20
00:01:14,820 --> 00:01:16,260
name function going to do?

21
00:01:16,290 --> 00:01:21,290
What would we want our future selves or another user who's using this function

22
00:01:21,300 --> 00:01:22,530
to know about it? Well,

23
00:01:22,530 --> 00:01:27,530
it's going to take a first and last name and format,

24
00:01:29,360 --> 00:01:30,193
it.

25
00:01:33,110 --> 00:01:34,730
Notice how with docstrings

26
00:01:34,820 --> 00:01:39,440
you can actually write strings that are multi-line. Normally,

27
00:01:39,440 --> 00:01:42,620
if I was to create a normal string, let's say, I dunno,

28
00:01:42,710 --> 00:01:44,530
a = "A String".

29
00:01:46,370 --> 00:01:47,720
If I hit the enter key,

30
00:01:47,780 --> 00:01:51,770
I'm going to get a warning because it's going to interpret this as the end of

31
00:01:51,770 --> 00:01:52,603
this line.

32
00:01:53,090 --> 00:01:57,920
And it won't see this closing quotation mark as being a part of this string.

33
00:01:58,670 --> 00:02:03,080
But when we use a docstring, we can write as many lines as we want

34
00:02:03,380 --> 00:02:07,220
and it will be interpreted all as the same thing altogether,

35
00:02:07,490 --> 00:02:11,210
as if it was fitted onto the same line like this.

36
00:02:12,470 --> 00:02:17,330
Now that we've added our docstring, it's time to see what it looks like. Now,

37
00:02:17,330 --> 00:02:21,590
if I call this function format_name, and I open up the parentheses,

38
00:02:21,890 --> 00:02:26,890
you can see that the text we wrote here now gets populated in the documentation.

39
00:02:27,650 --> 00:02:31,430
It takes the first and last name and formats it to return the title

40
00:02:31,430 --> 00:02:32,690
case version of the name.

41
00:02:33,650 --> 00:02:37,850
So this is a way for you to be able to start documenting your functions and

42
00:02:37,850 --> 00:02:40,460
giving each function a little bit of an explainer.

43
00:02:41,120 --> 00:02:46,120
Now you can also use this as a multiline comment.

44
00:02:46,460 --> 00:02:49,700
So notice how when we write a comment and we go to the next line

45
00:02:49,760 --> 00:02:50,900
it becomes code again.

46
00:02:51,470 --> 00:02:54,860
Now you can in fact use something like this

47
00:02:55,190 --> 00:02:58,850
where you just comment as many lines as you like

48
00:02:59,140 --> 00:03:02,050
and this will be interpreted as a comment

49
00:03:02,350 --> 00:03:05,500
as long as it's not assigned to anything. So for example,

50
00:03:05,500 --> 00:03:06,820
if I create a variable

51
00:03:07,150 --> 00:03:11,290
then this is now a piece of code. Because it's a little bit confusing

52
00:03:11,320 --> 00:03:15,700
the official Python guidance is actually to avoid multiline comments like this.

53
00:03:15,910 --> 00:03:20,910
What is actually much easier is to just write your multiline comment and then to

54
00:03:21,760 --> 00:03:26,380
highlight all of it and then to hit command + forward slash or control + forward

55
00:03:26,380 --> 00:03:27,370
slash on Windows.

56
00:03:28,030 --> 00:03:32,350
That's a much better way of differentiating the comment from actual pieces of

57
00:03:32,350 --> 00:03:33,183
code.

58
00:03:33,730 --> 00:03:38,710
Have a go at adding docstrings to the other functions that you've created and

59
00:03:38,710 --> 00:03:41,110
see it show up when you call your functions.