1
00:00:00,600 --> 00:00:01,800
Instructor: Let's talk about

2
00:00:01,800 --> 00:00:04,590
another developer fundamental.

3
00:00:04,590 --> 00:00:07,443
And this one is commenting your code.

4
00:00:08,310 --> 00:00:11,070
Up until now, you may have seen me comment,

5
00:00:11,070 --> 00:00:12,993
add comments to our scripts.

6
00:00:13,860 --> 00:00:15,030
For example,

7
00:00:15,030 --> 00:00:18,540
right here, I added a comment of booleans.

8
00:00:18,540 --> 00:00:21,660
And this tells the Python interpreter,

9
00:00:21,660 --> 00:00:23,160
hey, this is a comment.

10
00:00:23,160 --> 00:00:24,450
Don't run this.

11
00:00:24,450 --> 00:00:25,740
It's just for me.

12
00:00:25,740 --> 00:00:28,920
You can just ignore it and skip over to line 2.

13
00:00:28,920 --> 00:00:31,650
And you saw that I simply did that in Python

14
00:00:31,650 --> 00:00:33,090
with the # sign.

15
00:00:33,090 --> 00:00:36,990
As soon as Python sees a # sign, it adds a comment.

16
00:00:36,990 --> 00:00:38,910
And you can do that after a line as well.

17
00:00:38,910 --> 00:00:43,910
I can say this assigns to a variable.

18
00:00:46,650 --> 00:00:49,020
And although this may look like two lines,

19
00:00:49,020 --> 00:00:52,560
it's actually just the word wrapping that's happening.

20
00:00:52,560 --> 00:00:53,910
And you can see that the interpreter

21
00:00:53,910 --> 00:00:57,030
just completely ignores these comments.

22
00:00:57,030 --> 00:01:00,510
Now, commenting sounds very, very simple,

23
00:01:00,510 --> 00:01:02,040
but it's an important concept.

24
00:01:02,040 --> 00:01:04,650
And if you wanna be a good programmer,

25
00:01:04,650 --> 00:01:08,010
in all languages, we have commenting,

26
00:01:08,010 --> 00:01:11,163
but there's good ways and bad ways of commenting.

27
00:01:12,210 --> 00:01:14,490
And this is something that comes with practice.

28
00:01:14,490 --> 00:01:18,033
But here are some key guidelines.

29
00:01:18,870 --> 00:01:21,420
When you're commenting your code,

30
00:01:21,420 --> 00:01:26,100
the idea is that you're adding valuable comments.

31
00:01:26,100 --> 00:01:30,060
That is, if I add a comment here that says,

32
00:01:30,060 --> 00:01:35,060
hey, this is assign name variable a value of Andrei string.

33
00:01:41,670 --> 00:01:45,510
A comment like this is not really good.

34
00:01:45,510 --> 00:01:46,800
Why is that?

35
00:01:46,800 --> 00:01:51,800
Well, because your code should be self-explanatory, right?

36
00:01:52,560 --> 00:01:56,910
The idea is for us to write code that is easy to read,

37
00:01:56,910 --> 00:01:58,140
easy to understand.

38
00:01:58,140 --> 00:02:00,180
It's not trying to be clever.

39
00:02:00,180 --> 00:02:02,760
Instead, it should read like English.

40
00:02:02,760 --> 00:02:04,950
And any Python programmer

41
00:02:04,950 --> 00:02:08,430
would know that here we're just simply adding Andrei

42
00:02:08,430 --> 00:02:10,259
as a value of name.

43
00:02:10,259 --> 00:02:11,910
We're assigning a variable.

44
00:02:11,910 --> 00:02:15,630
And adding a comment like this that's self-explanatory

45
00:02:15,630 --> 00:02:18,303
just adds clutter to your code.

46
00:02:19,320 --> 00:02:20,910
So there's a trade-off here.

47
00:02:20,910 --> 00:02:23,370
It's good to comment your code for,

48
00:02:23,370 --> 00:02:25,080
let's say, if you're working on teams

49
00:02:25,080 --> 00:02:26,610
and other developers come

50
00:02:26,610 --> 00:02:29,100
and they wanna understand your code,

51
00:02:29,100 --> 00:02:31,680
but you have to remember this principle

52
00:02:31,680 --> 00:02:34,143
of code being easy to read.

53
00:02:35,160 --> 00:02:39,450
The only time you wanna add comments to your code

54
00:02:39,450 --> 00:02:43,470
is, well, when something really, really important

55
00:02:43,470 --> 00:02:44,550
is happening

56
00:02:44,550 --> 00:02:47,550
where it might be a little complex,

57
00:02:47,550 --> 00:02:48,960
you first decide,

58
00:02:48,960 --> 00:02:52,830
hey, is this code written in a way that makes sense?

59
00:02:52,830 --> 00:02:55,420
For example, if this was variable a

60
00:02:56,400 --> 00:02:58,833
and this was variable b,

61
00:03:01,170 --> 00:03:04,140
well, this might be really hard for somebody to understand.

62
00:03:04,140 --> 00:03:06,570
So you might say that this is

63
00:03:06,570 --> 00:03:08,463
is cool flag,

64
00:03:09,690 --> 00:03:11,430
but before you add that comment,

65
00:03:11,430 --> 00:03:12,720
you wanna say to yourself,

66
00:03:12,720 --> 00:03:15,780
hmm, maybe my code is hard to read.

67
00:03:15,780 --> 00:03:19,380
Maybe I should just change the variable to is_cool

68
00:03:19,380 --> 00:03:21,303
to make it more understandable.

69
00:03:22,260 --> 00:03:26,670
Now, this is something that you improve upon more and more.

70
00:03:26,670 --> 00:03:30,060
And you do wanna use comments as an extra tool

71
00:03:30,060 --> 00:03:31,860
to make your code understandable.

72
00:03:31,860 --> 00:03:34,380
Maybe you write code that six months from now

73
00:03:34,380 --> 00:03:37,230
you wanna go back to understand what you did.

74
00:03:37,230 --> 00:03:38,280
but remember,

75
00:03:38,280 --> 00:03:42,330
more comments doesn't necessarily mean better code.

76
00:03:42,330 --> 00:03:47,330
You want to be concise and keeping things simple

77
00:03:47,520 --> 00:03:50,100
while adding comments only when necessary

78
00:03:50,100 --> 00:03:52,380
to help others understand your code,

79
00:03:52,380 --> 00:03:56,760
not trying to make your unreadable code more readable.

80
00:03:56,760 --> 00:03:58,500
We'll explore this topic

81
00:03:58,500 --> 00:04:01,410
and give you advice on it throughout the course.

82
00:04:01,410 --> 00:04:04,500
But remember this key developer fundamental

83
00:04:04,500 --> 00:04:07,683
because you're gonna need it throughout your career.

84
00:04:08,610 --> 00:04:11,880
By the way, this article over here

85
00:04:11,880 --> 00:04:15,600
has some really important points

86
00:04:15,600 --> 00:04:18,149
that I think you'll really benefit from,

87
00:04:18,149 --> 00:04:21,750
especially in the commenting best practices.

88
00:04:21,750 --> 00:04:24,570
You can read some of the dos and don'ts

89
00:04:24,570 --> 00:04:28,200
and what some of the top programmers do when commenting.

90
00:04:28,200 --> 00:04:29,250
I know it sounds silly

91
00:04:29,250 --> 00:04:33,690
but it is an important concept that most courses overlook.

92
00:04:33,690 --> 00:04:36,810
So I highly recommend you read over this.

93
00:04:36,810 --> 00:04:39,450
I'll link to it in the resources

94
00:04:39,450 --> 00:04:41,253
and I'll see you in the next video.