WEBVTT

0
00:00.610 --> 00:09.910
Welcome! In this lecture, I'm going to explain common naming conventions among Gophers. When I say do or don't

1
00:09.940 --> 00:11.980
it's always up to you.

2
00:12.040 --> 00:16.240
I'll be talking about conventions, not about the rules. By the way,

3
00:16.300 --> 00:22.590
this is an optional lecture. So you can always come back to this lecture anytime you want.

4
00:22.610 --> 00:25.000
OK, let's get started.

5
00:25.110 --> 00:27.590
Let's take a look at a real life code example.

6
00:28.860 --> 00:37.100
Intentionally, I trimmed some parts of this code
and I changed it into this non-idiomatic version.

7
00:37.180 --> 00:45.520
By the way, "non-idiomatic" means "not preferred" usage and, "idiomatic" means preferred usage. In this code,

8
00:45.520 --> 00:52.060
there are many things that you didn't learn about yet but it still can give you a few clues about how

9
00:52.060 --> 00:56.260
not idiomatic and idiomatic code look like.

10
00:57.980 --> 00:59.250
So what's the problem with this code?

11
00:59.340 --> 01:09.200
Well, this code is unnecessarily verbose.
I mean everything has been declared with English words.

12
01:09.330 --> 01:16.110
You may think that this is easy to understand but words like buffer size and error are used so many

13
01:16.110 --> 01:24.940
times in Go code that we usually don't name them like this. We love concise code. This code is in a small

14
01:24.940 --> 01:26.850
scope. By small scope,

15
01:27.010 --> 01:34.840
I'm talking about that, (it's) in a very short function.
So naming things like this is not idiomatic in this

16
01:34.840 --> 01:35.950
short scope.

17
01:36.460 --> 01:41.770
And from the readability and maintainability perspective, this code is not good.

18
01:41.770 --> 01:44.280
Now let's take a look at its original version.

19
01:47.380 --> 01:54.960
This code is very concise and idiomatic and it's easy to understand and maintain. By the way, this code

20
01:55.050 --> 01:56.870
is from the (Go) standard library's

21
01:56.870 --> 01:59.160
bytes.Buffer package.

22
01:59.160 --> 02:01.420
It's a very popular package by the way.

23
02:01.710 --> 02:13.070
Alright, let's analyze this code. First, notice the abbreviations. Here b means buffer. It's the first parameter

24
02:13.090 --> 02:19.240
of the read function: b buffer.
n means the number of bytes read.

25
02:19.270 --> 02:24.850
This is the first result value of the read function and,
off means offset.

26
02:25.010 --> 02:27.780
It's a variable of the buffer type.

27
02:27.980 --> 02:32.670
People sometimes criticize Go that idiomatic names are cryptic.

28
02:32.720 --> 02:40.170
That's because they don't know about the common conventions or they don't read enough Go code. However,

29
02:40.200 --> 02:45.930
once you learn the common naming conventions, you'll be able to read almost any Go code.

30
02:46.140 --> 02:52.890
So if you want to write idiomatic Go code, I recommend reading more Go code, especially from the standard

31
02:52.890 --> 02:54.150
library itself.

32
02:56.710 --> 02:58.330
Let's take a look at some example

33
02:58.330 --> 03:00.280
common abbreviations.

34
03:00.640 --> 03:02.990
You don't have to memorize this of course.

35
03:03.070 --> 03:05.010
You'll get used to it in time.

36
03:05.020 --> 03:06.440
There is no rush.

37
03:06.490 --> 03:12.370
These names are used in Go, especially in the Go standard library. Just pause the video now and take

38
03:12.370 --> 03:15.160
a look at them. Try to find some patterns.

39
03:20.650 --> 03:24.720
Here is another list. Again, pause the video now and take a look at them.

40
03:24.740 --> 03:26.700
Try to find some patterns again.

41
03:36.090 --> 03:40.140
And this is the last one.
I'm trying to let you find the patterns by yourself.

42
03:40.140 --> 03:43.010
I'm not expecting you to memorize all this stuff.

43
03:43.020 --> 03:43.790
Don't do that.

44
03:50.670 --> 03:53.310
So why naming is important.

45
03:53.310 --> 03:59.640
The naming is important because it is very critical for readability and if you can't read the code how

46
03:59.640 --> 04:01.380
can you maintain it?

47
04:01.380 --> 04:02.440
Is it possible?

48
04:02.550 --> 04:04.010
I don't think so.

49
04:04.080 --> 04:10.140
Imagine a book that you don't understand and someone comes to you and say that can you fix the typos

50
04:10.140 --> 04:15.270
in it. Can really do it? Without understanding it, you can't fix it.

51
04:15.270 --> 04:18.390
So naming your code properly is the same thing.

52
04:18.690 --> 04:27.430
If you can't understand it, you can't fix it, so you can't add new features to it and so on. Here's the most

53
04:27.430 --> 04:28.880
common idiom.

54
04:29.110 --> 04:34.800
Use the first few letters of the words like this.
To do that successfully,

55
04:34.800 --> 04:39.520
as I said, you need to read a lot of Go code.
It's actually not that hard
(you may say I'm a dreamer but I'm not the only one).

56
04:39.660 --> 04:41.380
You just need to be curious.

57
04:41.400 --> 04:45.810
Open a random source code from the standard library and start reading it.

58
04:45.810 --> 04:50.350
It's open source.
After some time, you'll get better at it.

59
04:50.640 --> 04:59.670
By the way, you can find a few example links for idiomatic Go code in the resources. As I showed you, using

60
04:59.670 --> 05:06.570
fewer letters in smaller scopes will clarify the code and make it easier to maintain. For example,

61
05:06.570 --> 05:08.770
take a look at this declaration.

62
05:08.790 --> 05:12.360
Imagine that this variable is declared within a function.

63
05:12.360 --> 05:15.490
If so, this is a very verbose naming.

64
05:15.480 --> 05:20.770
Now, let's take a look at this one. It's just n. When used correctly,

65
05:20.790 --> 05:23.090
it is very easy to read and type.

66
05:23.370 --> 05:30.230
If you're coming from Java or C#, I know that these naming conventions may look weird to you. In Java,

67
05:30.260 --> 05:37.620
and C#, it's a best practice to use readable longer names and using comments is anti-pattern in there

68
05:37.860 --> 05:39.190
but is not so in Go.

69
05:39.270 --> 05:42.570
Because we understand what the abbreviations mean.

70
05:42.580 --> 05:48.670
However, don't use the abbreviations everywhere, especially in larger scopes like in a package scope

71
05:48.750 --> 05:49.830
for example.

72
05:49.830 --> 05:56.790
That would be extreme. For larger scopes use the complete words, do not make them shorter.

73
05:56.790 --> 05:59.520
Let's take a look at an example declaration.

74
05:59.550 --> 06:04.010
Imagine this variable is declared in the package block of the file package.

75
06:04.260 --> 06:10.690
So it's a package level variable. So it's in a larger scope. So don't use abbreviations there.

76
06:11.070 --> 06:16.750
Also, note that the mixed caps in the name. "file" starts with a lowercase letter.

77
06:16.840 --> 06:21.310
However, "Closed" word starts with an uppercase letter. In Go,

78
06:21.330 --> 06:26.210
we use these mixed caps style. Use mixed caps.

79
06:26.250 --> 06:33.360
This example tells it all. "m" in mixed is lowered. "C" in caps is capitalized.

80
06:33.360 --> 06:34.950
Here is another example.

81
06:34.950 --> 06:37.490
PlayerScore. A struct type.

82
06:37.680 --> 06:40.430
It uses a capital letter for P.

83
06:40.470 --> 06:47.090
It's ok. It's because this name should have been exported from a package. "Score" also starts with a capital letter.

84
06:47.100 --> 06:57.100
That's OK too. Use all capital letters for common acronyms like this. API is a well-known acronym.

85
06:57.130 --> 06:59.830
It means Application Programming Interface.

86
06:59.950 --> 07:03.440
So it's OK to use it with capital letters like this.

87
07:03.880 --> 07:08.700
Let's take a look at another declaration. Do not name like this.

88
07:08.730 --> 07:12.800
It's not idiomatic.
And, do not stutter.

89
07:12.800 --> 07:16.440
This means that do not use the same words again and again.

90
07:16.550 --> 07:20.790
For example, here is a playerScore name which is in the player package.

91
07:21.000 --> 07:22.000
It stutters.

92
07:22.040 --> 07:29.800
It uses the player twice, successively, instead of this, do this instead. player.Score.

93
07:30.170 --> 07:32.410
This is better and much more readable.

94
07:35.680 --> 07:42.900
And lastly, do not use underscores in names or do not name them like this.

95
07:42.960 --> 07:46.920
They are not idiomatic and they look terrible to my eye (also for other Gophers).

96
07:46.920 --> 07:48.840
Let's take a look at another example.

97
07:48.840 --> 07:55.620
This declaration names MaxTime time with all capital letters and with an underscore character.

98
07:55.620 --> 07:57.380
This is not idiomatic.

99
07:57.420 --> 07:59.540
Let me show you a better version of it.

100
08:00.210 --> 08:01.950
This one is idiomatic.

101
08:01.950 --> 08:05.170
It uses mixed caps.

102
08:05.200 --> 08:07.360
Let me show you one last example.

103
08:07.360 --> 08:11.290
This constant is declared with a single letter.

104
08:11.290 --> 08:14.550
This is also ok and idiomatic.

105
08:14.690 --> 08:15.590
Alright.

106
08:15.590 --> 08:16.370
That was all.

107
08:16.370 --> 08:18.840
Now you know how to use idiomatic names in Go.

108
08:19.040 --> 08:23.100
For more information, please check out the resources as well.

109
08:23.120 --> 08:23.720
Alright. Bye for now.