How to Do X in Go

I have worked with Go in the past but I have not worked with it in some time. As a result, I forgot some of the conventions and ways of doing things.

To make it easier in future for myself and anyone else starting with Go (coming from another language) I have made this living document.

Environment Setup

A good Go version manager can be found here.

Using gvm simplifies the below as gvm will set up and manage the required go environment variables for you.

Gvm also greatly simplifies working with multiple versions of Go at the same time.

GOBIN

This is the folder where GO places binaries that have been built or/and installed. Some programs may need the full absolute path but using the $GOPATH command line variable should work most of the time. In your .zshrc or .bashrc export the GOBIN path as follows:

export GOBIN=$GOPATH/bin

Add GOBIN to your path so you can see binaries from there on your path:

export PATH=$PATH:$GOBIN

VS Code - Disable Annoying Linting Warnings For No Comments

Add the following to your VS Code settings.json file:

  "go.lintFlags": [
	  "--exclude=\"\bexported \\w+ (\\S*['.]*)([a-zA-Z'.*]*) should have comment or be unexported\b\""
  ],

Go path

export GOPATH=$HOME/code/go

In my case this is where it is, you can create this anywhere you want.

The GOPATH is where dependencies that you go get are saved to (it is sort of like your .m2/repo folder with Java and Maven).

The root of my GOPATH has the following in it (this will change greatly depending on the dependencies you have gotten):

bin/
overlay/
src/

Go root

This is the equivalent of Java's JAVA_HOME. gvm set mine to something like the following /Users/someuser/.gvm/gos/go1.12.7

My GOROOT has the following files in it:

AUTHORS
CONTRIBUTING.md
CONTRIBUTORS
LICENSE
PATENTS
README.md
VERSION
api/
bin/
doc/
favicon.ico
lib/
manifest
misc/
pkg/
robots.txt
src/
test/

IDE

VS code together with the official VS Code Go extension is rock solid.

This extension will use go get to install the requirements you need and other things like the Go formatter and lindter which the extension uses to check and manage code in IDE windows.

In my case the following Go tools were installed by the plugin on installing a new version of Go:

Installing 9 tools at /path/to/your/username/go/bin
  go-outline
  go-symbols
  guru
  gorename
  dlv
  gocode-gomod
  godef
  goreturns
  golint

Installing github.com/mdempsky/gocode SUCCEEDED
Installing github.com/uudashr/gopkgs/cmd/gopkgs SUCCEEDED
Installing github.com/ramya-rao-a/go-outline SUCCEEDED
Installing github.com/acroca/go-symbols SUCCEEDED
Installing golang.org/x/tools/cmd/guru SUCCEEDED
Installing golang.org/x/tools/cmd/gorename SUCCEEDED
Installing github.com/go-delve/delve/cmd/dlv SUCCEEDED
Installing github.com/stamblerre/gocode SUCCEEDED
Installing github.com/rogpeppe/godef SUCCEEDED
Installing github.com/sqs/goreturns SUCCEEDED
Installing golang.org/x/lint/golint SUCCEEDED

All tools successfully installed. You're ready to Go :).

Setting up VS Code to Use GVM

Do what is described here

Setting up a new project

Follow the last step here (i.e. the gvm part)

Cheatsheet

Definitions:

• Language: This is enforced by the language.
• Convention: This is the idiomatic Go way of doing this.

Enum

type Compass int

const (
  NORTH Compass = iota +1,
  _
  SOUTH,
  EAST,
  WEST
)

var direction Compass

direction = SOUTH

• iota+1 followed by _: This will automatically assign SOUTH to the int value 2, EAST to 3 and WEST to 4.
  • You need the _ if you want to start at 1 instead of 0 otherwise you can leave out the _ and SOUTH would then be 1 and NORTH 0.
  • _ is used to force iota to increment without assigning it to anything. This means you can have multiple _ to force it to increment further.
  • iota + 1 controls how incrementing will work, in this case, it is saying increment by 1 each time. iota * 2 would increment iota by 1 and multiply by 2 each time a new enum is assigned.
  • Assigning the first value to something than just iota is an easy way to verify if the enum has been initialized. If the enum has not been initialized it will have a value 0.
• iota: Used to auto increment the int value for the other enums.
• type Compass int: Assigning this only to the first type and not the other types explicitly will automatically make SOUTH, EAST and WEST of type compass.

To get the value of an enum you need to cast/coerse it e.g. int(NORTH)

• To understand iota better see here.
• To understand this enum syntax better see here.
• For a detailed article on iota and enums see here

Output Enum as String Value in JSON Output

You need to implement the following 2 methods on the enum type:

func (c Compass) MarshalJSON() ([]byte, error) {
  // ...
}

// And
func (c *Compass) UnmarshalJSON(b []byte) error {
  // ...
}

For the Compass example I would add the following:

func (c Compass) String() string {
      switch c {
        case NORTH:
            return "North"
        case SOUTH:
            return "South"
        case EAST:
            return "East"
        case WEST:
            return "West"
      }
      return ""
}

var stringToCompass = map[string]Compass {
  "NORTH": NORTH,
  "SOUTH": SOUTH,
  "EAST": EAST,
  "WEST": WEST,
}

func (c Compass) MarshalJSON() ([]byte, error) {
	buffer := bytes.NewBufferString(`"`)
	buffer.WriteString(c.String())
	buffer.WriteString(`"`)
	return buffer.Bytes(), nil
}

func (c *Compass) UnmarshalJSON(b []byte) error {
	var j string
	err := json.Unmarshal(b, &j)
	if err != nil {
		return err
	}
	*c = stringToCompass(j)
	return nil
}

To this gist for another example of doing this.

Interface / Inheritance

Golang does inheritance through composition. So for example if I have the following struct, interface and implementation:

type Person interface {
  Greet() string
}

type Student struct {
  Name string
}

func (s Student) Greet() string {
  return fmt.Sprintf("Hello %s", s.Name)
}

Now if I have another type called say Professional which I want to inherit everything from Student I do so as follows:

type Professional struct {
  Student
  YearsExperience uint
}

Anything that is of type Professional now has access to Students methods as below:

student := Student {
  Name: "John",
}

professional := Professional{
		Student: Student{Name: "Sally"},
}

fmt.Println(student.Greet())
fmt.Println(professional.Greet())

The full code for this is below:

package main

import (
	"fmt"
)

type Person interface {
	Greet() string
}

type Student struct {
	Name string
}

func (s Student) Greet() string {
	return fmt.Sprintf("Hello %s", s.Name)
}

type Professional struct {
	Student
	YearsExperience uint
}

func main() {
	student := Student{
		Name: "John",
	}

	professional := Professional{
		Student: Student{Name: "Sally"},
	}

	fmt.Println(student.Greet())
	fmt.Println(professional.Greet())
}

Which outputs:

Hello John
Hello Sally

See this playground to play around with this.

Pass By...

See this gist to understand the different ways of using pass by reference and pass by value.

Patterns

Must

This is the convention of prefixing method names of methods that panic on errors encountered as opposed to returning the error.

For example the none Must version of some validation method:

func ValidateBar() (string, error) {
  // ...
  err := validateSomeField()

  if err != nil {
    return "", err
  }
  // ...
  // ...
  // ...

  return someStringVar, nil
}

The Must version of this is:

func MustValidateBar() string {
  // ...
  err := validateSomeField()

  if err != nil {
    panic(err)
  }
  // ...
  // ...
  // ...

  return someStringVar
}