Welcome! In this lecture, I'm going to explain common naming conventions among Gophers. When I say do or don't
it's always up to you.
I'll be talking about conventions, not about the rules. By the way,
this is an optional lecture. So you can always come back to this lecture anytime you want.
OK, let's get started.
Let's take a look at a real life code example.
Intentionally, I trimmed some parts of this code and I changed it into this non-idiomatic version.
By the way, "non-idiomatic" means "not preferred" usage and, "idiomatic" means preferred usage. In this code,
there are many things that you didn't learn about yet but it still can give you a few clues about how
not idiomatic and idiomatic code look like.
So what's the problem with this code?
Well, this code is unnecessarily verbose. I mean everything has been declared with English words.
You may think that this is easy to understand but words like buffer size and error are used so many
times in Go code that we usually don't name them like this. We love concise code. This code is in a small
scope. By small scope,
I'm talking about that, (it's) in a very short function. So naming things like this is not idiomatic in this
short scope.
And from the readability and maintainability perspective, this code is not good.
Now let's take a look at its original version.
This code is very concise and idiomatic and it's easy to understand and maintain. By the way, this code
is from the (Go) standard library's
bytes.Buffer package.
It's a very popular package by the way.
Alright, let's analyze this code. First, notice the abbreviations. Here b means buffer. It's the first parameter
of the read function: b buffer. n means the number of bytes read.
This is the first result value of the read function and, off means offset.
It's a variable of the buffer type.
People sometimes criticize Go that idiomatic names are cryptic.
That's because they don't know about the common conventions or they don't read enough Go code. However,
once you learn the common naming conventions, you'll be able to read almost any Go code.
So if you want to write idiomatic Go code, I recommend reading more Go code, especially from the standard
library itself.
Let's take a look at some example
common abbreviations.
You don't have to memorize this of course.
You'll get used to it in time.
There is no rush.
These names are used in Go, especially in the Go standard library. Just pause the video now and take
a look at them. Try to find some patterns.
Here is another list. Again, pause the video now and take a look at them.
Try to find some patterns again.
And this is the last one. I'm trying to let you find the patterns by yourself.
I'm not expecting you to memorize all this stuff.
Don't do that.
So why naming is important.
The naming is important because it is very critical for readability and if you can't read the code how
can you maintain it?
Is it possible?
I don't think so.
Imagine a book that you don't understand and someone comes to you and say that can you fix the typos
in it. Can really do it? Without understanding it, you can't fix it.
So naming your code properly is the same thing.
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
common idiom.
Use the first few letters of the words like this. To do that successfully,
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).
You just need to be curious.
Open a random source code from the standard library and start reading it.
It's open source. After some time, you'll get better at it.
By the way, you can find a few example links for idiomatic Go code in the resources. As I showed you, using
fewer letters in smaller scopes will clarify the code and make it easier to maintain. For example,
take a look at this declaration.
Imagine that this variable is declared within a function.
If so, this is a very verbose naming.
Now, let's take a look at this one. It's just n. When used correctly,
it is very easy to read and type.
If you're coming from Java or C#, I know that these naming conventions may look weird to you. In Java,
and C#, it's a best practice to use readable longer names and using comments is anti-pattern in there
but is not so in Go.
Because we understand what the abbreviations mean.
However, don't use the abbreviations everywhere, especially in larger scopes like in a package scope
for example.
That would be extreme. For larger scopes use the complete words, do not make them shorter.
Let's take a look at an example declaration.
Imagine this variable is declared in the package block of the file package.
So it's a package level variable. So it's in a larger scope. So don't use abbreviations there.
Also, note that the mixed caps in the name. "file" starts with a lowercase letter.
However, "Closed" word starts with an uppercase letter. In Go,
we use these mixed caps style. Use mixed caps.
This example tells it all. "m" in mixed is lowered. "C" in caps is capitalized.
Here is another example.
PlayerScore. A struct type.
It uses a capital letter for P.
It's ok. It's because this name should have been exported from a package. "Score" also starts with a capital letter.
That's OK too. Use all capital letters for common acronyms like this. API is a well-known acronym.
It means Application Programming Interface.
So it's OK to use it with capital letters like this.
Let's take a look at another declaration. Do not name like this.
It's not idiomatic. And, do not stutter.
This means that do not use the same words again and again.
For example, here is a playerScore name which is in the player package.
It stutters.
It uses the player twice, successively, instead of this, do this instead. player.Score.
This is better and much more readable.
And lastly, do not use underscores in names or do not name them like this.
They are not idiomatic and they look terrible to my eye (also for other Gophers).
Let's take a look at another example.
This declaration names MaxTime time with all capital letters and with an underscore character.
This is not idiomatic.
Let me show you a better version of it.
This one is idiomatic.
It uses mixed caps.
Let me show you one last example.
This constant is declared with a single letter.
This is also ok and idiomatic.
Alright.
That was all.
Now you know how to use idiomatic names in Go.
For more information, please check out the resources as well.
Alright. Bye for now.