1
00:00:00,000 --> 00:00:04,920
Okay, so I sort of purposely skipped over one of the really

2
00:00:05,040 --> 00:00:07,890
basic features that pretty much every programming language

3
00:00:07,900 --> 00:00:09,120
has, and that's code commenting.

4
00:00:09,240 --> 00:00:12,450
Now you've probably actually seen this before where I just

5
00:00:12,450 --> 00:00:15,400
write a number sign and then anything in here,

6
00:00:15,440 --> 00:00:18,530
and as soon as I hit 'Enter', Python does not complain, but

7
00:00:18,540 --> 00:00:21,060
if I type anything in here, it's going to complain.

8
00:00:21,060 --> 00:00:24,400
Now the difference is this is a code comment.

9
00:00:24,470 --> 00:00:29,400
Anything after this symbol here is considered a comment,

10
00:00:29,400 --> 00:00:31,300
and Python just says, "Oh, that's not for me.

11
00:00:31,300 --> 00:00:33,750
That's probably for my human overlords.

12
00:00:33,760 --> 00:00:35,580
So don't do anything with it".

13
00:00:35,740 --> 00:00:38,770
Now comments are a really good way of maintaining your code.

14
00:00:38,780 --> 00:00:41,110
It is a very healthy habit to get into,

15
00:00:41,120 --> 00:00:44,260
and I would say whenever you can, comment your code; and the

16
00:00:44,270 --> 00:00:47,970
more complex your code gets, the more comments it probably

17
00:00:47,980 --> 00:00:53,660
needs. So let's just start fresh here, and let's say we have

18
00:00:53,690 --> 00:00:58,340
a variable called 'name', and it's going to say, "What is your

19
00:00:58,340 --> 00:01:00,600
name?", and it's just going to ask for someone's name.

20
00:01:01,600 --> 00:01:05,900
Now we could put a comment here saying, "# This will ask for

21
00:01:05,900 --> 00:01:07,400
the user's name".

22
00:01:08,300 --> 00:01:11,100
And so whenever someone comes into your code and they say,

23
00:01:11,100 --> 00:01:12,000
"Oh, what is name?"

24
00:01:12,000 --> 00:01:15,770
'name = "What is your name?" They can also read the

25
00:01:15,770 --> 00:01:17,800
comment that says, "# This will ask for the users name".

26
00:01:17,840 --> 00:01:22,410
Now, we are familiar with the 'input' function by now, so we

27
00:01:22,410 --> 00:01:26,080
know what this is going to do, but someone else may not.

28
00:01:26,200 --> 00:01:30,100
Another example of this could be a dictionary called 'person',

29
00:01:30,100 --> 00:01:32,200
and we could try to get someone's 'age'.

30
00:01:33,000 --> 00:01:37,900
And so we can say, 'person.get('age')'. Now by default,

31
00:01:37,900 --> 00:01:41,100
'get' always returns 'None' if there is nothing there.

32
00:01:41,140 --> 00:01:44,380
But because that's a default parameter, you don't actually

33
00:01:44,390 --> 00:01:45,310
need to specify that.

34
00:01:45,320 --> 00:01:47,530
A lot of people, surprisingly don't actually know that.

35
00:01:47,540 --> 00:01:51,830
So what you could say in this comment, is "#Get the person's

36
00:01:51,920 --> 00:01:55,990
age or return None", or not return because it's not,

37
00:01:56,000 --> 00:02:01,900
I guess it could return, or assign, rather, "assign None if

38
00:02:01,900 --> 00:02:05,100
an age wasn't found".

39
00:02:05,100 --> 00:02:07,500
And so it's going to ask what my name is, that doesn't really

40
00:02:07,500 --> 00:02:12,600
matter. My name is "Kalob", and the 'age' here we do 'age',

41
00:02:12,600 --> 00:02:16,500
it's nothing. 'type(age)'

42
00:02:16,500 --> 00:02:21,400
is 'NoneType' because there was no age in here, it defaulted

43
00:02:21,780 --> 00:02:22,710
to 'None'.

44
00:02:24,100 --> 00:02:26,400
And that's a good use of using comments.

45
00:02:26,400 --> 00:02:28,300
Now another place you're going to want to use comments, and

46
00:02:28,390 --> 00:02:29,430
you'll see these all over the place,

47
00:02:29,440 --> 00:02:31,410
is inside of functions as well.

48
00:02:31,420 --> 00:02:35,600
So let's create a function 'def 'func_name', and it's going to

49
00:02:35,600 --> 00:02:40,800
do a thing, so 'return "Something in here"'.

50
00:02:40,860 --> 00:02:42,600
Now you can leave comments in here as well.

51
00:02:42,600 --> 00:02:45,700
So, "#This is going to do a thing".

52
00:02:45,700 --> 00:02:47,900
It's a terrible code comment, by the way, because it's not

53
00:02:47,940 --> 00:02:50,630
very explicit. It doesn't tell you what it's going to do.

54
00:02:50,640 --> 00:02:52,760
It just says it's going to do a thing. That's not helpful.

55
00:02:52,860 --> 00:02:56,070
So when you're writing your code comments, try to be a little bit

56
00:02:56,070 --> 00:02:58,700
better than me in this demo video.

57
00:02:59,500 --> 00:03:02,300
But in a function, there's another way to write code comments,

58
00:03:02,340 --> 00:03:03,980
and this thing is called a Docstring.

59
00:03:03,990 --> 00:03:08,780
So it starts with either three apostrophes, or it's going

60
00:03:08,780 --> 00:03:11,100
to start with three quotation marks.

61
00:03:11,100 --> 00:03:13,400
I like using the quotation marks, but it doesn't really matter

62
00:03:13,500 --> 00:03:14,510
which one you decide to use.

63
00:03:14,600 --> 00:03:19,100
And then here you could say, "This is a function that does

64
00:03:19,190 --> 00:03:28,710
a thing", and then, "It's going to return a string", and maybe

65
00:03:28,710 --> 00:03:29,900
some other notes.

66
00:03:30,900 --> 00:03:33,000
Now, we saw this when we were learning about strings

67
00:03:33,000 --> 00:03:35,300
way, way, way, way back

68
00:03:35,300 --> 00:03:39,600
there are lot of videos ago, but this is called a Docstring.

69
00:03:39,600 --> 00:03:41,200
And so what you can do,

70
00:03:41,220 --> 00:03:44,520
is have multiple lines in here, and you don't have to worry

71
00:03:44,520 --> 00:03:49,400
about putting a number sign in front of every single line.

72
00:03:49,400 --> 00:03:52,000
It prevents this from needing to happen.

73
00:03:52,000 --> 00:03:54,900
[no audio]

74
00:03:54,900 --> 00:03:57,200
Now, one last reason to write comments,

75
00:03:57,220 --> 00:03:59,920
a lot of people when they're just learning to program, they

76
00:03:59,930 --> 00:04:01,270
say, "Oh, I don't need to write comments.

77
00:04:01,280 --> 00:04:02,410
I know exactly what I'm doing.

78
00:04:02,420 --> 00:04:04,930
I know myself well enough to understand why I named a variable that."

79
00:04:04,930 --> 00:04:08,000
And for the most part, that could very well be true.

80
00:04:08,080 --> 00:04:11,890
But three months from now, six months from now, nine months

81
00:04:11,900 --> 00:04:15,160
from now, you are going to have a lot of different experiences

82
00:04:15,170 --> 00:04:17,860
between now and then, and your brain is actually going to

83
00:04:17,870 --> 00:04:21,459
change a little bit, and you may not fully understand or

84
00:04:21,459 --> 00:04:23,899
fully remember all the code that you wrote.

85
00:04:23,940 --> 00:04:27,870
So writing comments like Docstrings here is really helpful.

86
00:04:28,120 --> 00:04:30,700
So nine months from now, you could look at 'func_name', and

87
00:04:30,710 --> 00:04:32,350
you could say, "What is it supposed to do?

88
00:04:32,360 --> 00:04:34,480
Like, I don't understand why you even have this in here".

89
00:04:34,640 --> 00:04:39,140
But in the Docstrings, this could say, "This is a demo function

90
00:04:39,500 --> 00:04:41,600
and is not used at all.

91
00:04:41,600 --> 00:04:46,400
It's allowed to be deleted in the future".

92
00:04:46,460 --> 00:04:48,650
Let's go ahead and get rid of this stuff.

93
00:04:49,900 --> 00:04:52,000
And so when you come back to this code nine months from now,

94
00:04:52,000 --> 00:04:53,200
you can say 'func_name'.

95
00:04:53,210 --> 00:04:56,510
"This is a demo function, and is not used at all. It's

96
00:04:56,510 --> 00:04:57,900
allowed to be deleted in the future".

97
00:04:57,920 --> 00:05:00,710
Okay, so I've got a comment in here that tells me that this

98
00:05:00,720 --> 00:05:04,590
is likely not being used, so I could probably safely delete

99
00:05:04,600 --> 00:05:08,310
this. The other reason is you are going to be working with

100
00:05:08,320 --> 00:05:12,570
other people. Other programmers, other Python Devs are going

101
00:05:12,570 --> 00:05:14,500
to be looking at your code eventually, and you're going to

102
00:05:14,500 --> 00:05:15,700
be looking at their code,

103
00:05:15,700 --> 00:05:18,800
and if they have some complex function, you're going to want to

104
00:05:18,840 --> 00:05:21,470
know what it does, just like they're going to want to

105
00:05:21,470 --> 00:05:25,700
know what your code is doing, so leaving a comment is very, very helpful.

106
00:05:25,700 --> 00:05:30,900
Now, when it comes to basic things, for instance, a 'role

107
00:05:30,900 --> 00:05:32,600
= 'Student',

108
00:05:32,970 --> 00:05:35,590
well, that's pretty self explanatory,

109
00:05:35,600 --> 00:05:38,020
talking about a 'role = 'Student'.

110
00:05:38,020 --> 00:05:39,700
Now, we don't necessarily know what that 'role' is

111
00:05:39,700 --> 00:05:41,800
for, that might be worthy of a comment.

112
00:05:41,800 --> 00:05:45,500
But you don't need to leave a comment like, "This is a string",

113
00:05:45,500 --> 00:05:47,700
because anyone who's looking at this code is going to say,

114
00:05:47,700 --> 00:05:49,600
"Oh, that's obviously a string. I know that".

115
00:05:49,600 --> 00:05:53,600
So this is an example of a bad comment.

116
00:05:54,900 --> 00:05:57,000
Actually, I shouldn't say it's a bad comment, but it is a

117
00:05:57,000 --> 00:05:59,200
rather useless comment,

118
00:05:59,260 --> 00:06:01,610
everyone's going to know that this is a string.

119
00:06:01,670 --> 00:06:05,150
Now, if there was a bunch of logic in here, let's say there is

120
00:06:05,150 --> 00:06:08,400
30 lines of code, and this 'role' is going to change into

121
00:06:08,460 --> 00:06:09,810
maybe from a 'Student',

122
00:06:09,820 --> 00:06:12,480
it takes a string, and eventually it gets transformed into

123
00:06:12,480 --> 00:06:15,500
like a User Id, which is going to be an integer,

124
00:06:15,540 --> 00:06:18,150
then you might want to comment that because, again, there's

125
00:06:18,150 --> 00:06:21,000
something a little more complex, not just on the surface,

126
00:06:21,020 --> 00:06:23,510
but something complex that's happening in your code,

127
00:06:23,510 --> 00:06:24,900
that's worth commenting.

128
00:06:25,600 --> 00:06:27,800
So my advice is comment.

129
00:06:28,070 --> 00:06:31,610
And if you're ever wondering, "Kalob, where should I comment?

130
00:06:31,620 --> 00:06:33,170
Should I comment a particular function?

131
00:06:33,180 --> 00:06:34,280
Should I comment a string?"

132
00:06:34,320 --> 00:06:36,540
Honestly, I'm just going to tell you this right now,

133
00:06:36,550 --> 00:06:39,930
it is better to leave a bad comment than to leave no comments

134
00:06:39,940 --> 00:06:42,360
at all. 100% of the time

135
00:06:42,360 --> 00:06:45,700
it is better to leave a bad comment than no comment at all.

136
00:06:45,700 --> 00:06:46,700
[no audio]