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