Write Quality Code in Golang
Quality code has key elements, like no breaking bugs, concise syntax, adherence to best practices, and documentation. Golint checks for quality code in Golang.
Sep 24, 2020 • 8 Minute Read
Introduction
Discussing how to write quality code is the same type of conversation as discussing what the best cloud provider is. There are a ton of different theories, opinions, and speculations. But one thing holds true with writing code—it must have some key components, including:
- A confirmation that breaking bugs don't exist (it's inevitable to at least have a few bugs)
- Clear, concise syntax
- Best practices are followed for the language.
- Some sort of documentation.
A guide on every single best practice would most likely be over 20,000 words, which I'm sure you aren't interested in reading. Instead, this guide will go over four popular ways to ensure you're writing quality code with Golang.
To follow along with this guide, you should have:
- An understanding of Golang. Although you don't have to be an expert, this isn't a blog post on the basics of Go.
- Knowledge of development practices (linting, syntax highlighting, etc.)
Linting
Have you ever written code that worked but you didn't know if it was written the way it should be? For example, maybe you took a look at the way others were writing code and wondered, "Why doesn't mine look like that?" The thing is, you don't know whether the code you wrote or the other code is right.
That's just one example of where linting shines.
Linting, or a linter, in computer science is comprised of a few key components:
- Checks for errors
- Checks for bugs
- Checks for stylistic errors and syntax best practices
- Suspicious constructs (warnings about syntax errors, unused declared variables, deprecated functions, spacing and formatting, etc.)
Popular Linter for Go
There are a few highly popular general purpose linters, but there is one that is used widely throughout the Go community that was created specifically for Go, which is called Golint. You can find Golint on GitHub here.
Golint Example
Before using Golint, you'll have to install it.
go get -u golang.org/x/lint/golint
Once Golint is installed, you can run it against an existing Go file. For example, you can run Golint against the code below.
package Test
import (
"fmt"
)
func Demo() {
one := "one"
two := "one"
fmt.Println(one)
fmt.Println(two)
}
To run Golint against the above code, run the following command.
golint my_test.go
In the screenshot below, you can see that Golint already found an issue with the package name.
Although it's not something that would make the Go code fail, it is something that from a syntax perspective should be changed to follow best practices.
IDE Support
IDEs are integrated development environments, which means they're typically meant for one or more programming languages with proper support for the languages they support.
Some of the key features of an IDE include:
- Source/code editor
- Debugger
- Compiler
- Syntax highlighting for errors
- Auto-complete for functions, methods, etc.
Although there are many IDEs, there is one that is very popular in the Golang space.
GoLand
JetBrains is known for making well-working IDEs for almost all languages. GoLand is one of them.
GoLand is an IDE specific to Golang. Not only is GoLand cross-platform, but it has a few key features:
- Error detection on the fly with syntax highlighting
- Code completion
- Debugging
- Out-of-the-box support for Git
Documentation
Without documentation, no one has any idea what's happening. Let's take a scenario that's completely off-topic. Say you buy a piece of furniture without proper instructions, or even worse, with instructions that are very minimal and not helpful.
You can probably piece it together, but the experience you gain from it will be awful. You most likely won't buy anything from that vendor again.
The same thing holds true for code.
If you're creating an open source project or have a pitch that you would like to bring up for the team you're working on, without any data, or documentation, there's nothing to show. It's just an idea in your head that works great, but no one else knows how great it'll work.
Luckily, Golang has a great way to write documentation almost automatically with the Godoc documentation tool. Godoc extracts and generates documentation for Go programs.
Installing Godoc
To install Godoc, run the following command.
golang.org/x/tools/cmd/godoc
Using Godoc
To use Godoc, you can run the following command on a terminal.
godoc -http=:6060
You can then go to [localhost:6060](https://localhost:6060) and you will see documentation for:
- Standard libraries
- Third party libraries
- Packages you wrote
Creating Documentation
To create documentation, write a regular comment directly preceding a declaration on a function, type, constant, variable, or a complete package.
For more information on creating documentation, I recommend checking out the official Go docs found here.
Testing
Last but certainly not least, there is testing. There is a saying that holds true for any programming language:
The code doesn't exist unless there are tests.
Writing code and testing it locally is a practice that many developers use, but it doesn't help in almost any case. Once the code you're testing locally is committed to source control and others have their hands on it, the test you ran locally now holds zero value.
Without tests, you will have code that is simply a mystery.
Types of Tests
There are three primary ways to test:
- Unit tests
- Integration tests
- Mock tests
Unit tests test certain aspects of what you expect code to do. For example, say that you have a function that adds 1 + 1 when it runs. That means the anticipated result is two. The unit test would test that function and ensure the outcome is two.
Integration tests expose defects and interactions between integrated components, for example, testing against units like two functions.
Mock tests perform an almost-real implementation, but fake it. There are also mock tests that will create a real resource, but then delete it right after to ensure it's not just hanging around. For example, let's say you have a Terraform resource to create a resource group in Azure. Before implementing the code, you want to know if it actually works. A mock test will run, create the resource, confirm it exists, then delete the resource for you so it's not just hanging around.
Testing with Golang
In a lot of programming languages, you have to go to a third party to obtain a testing package. With Go, there's a testing package in the standard library, and it's literally called testing. Because the testing package is in the standard library, you don't have to install anything.
Below is an example of a test.
package Test
import (
"testing"
"github.com/stretchr/testify/assert"
)
func TestDemo(t *testing.T) {
one := "one"
two := "one"
assert.Equal(t, one, two, "the two variables should be the same value")
}
The test is to ensure that the variables one and two are the same value. To run the test, you can use the go test command in the same directory that the test resides in.
.png)
Conclusion
Whatever job you walk into, it's guaranteed that the idea of best practices won't always be the same across the board. Different people in different organizations will have different ideas on what that means. The best thing that you can do as a developer to practice quality code integration is to ensure you are doing everything you can to not only educate others, but also explain the process to achieve quality in a clear and concise manner.
