100 Go Mistakes on maladroit.dev

Any says nothing

Mon, 01 Jan 0001 00:00:00 +0000

The empty interface{} or any is considered to be an over-generalization.

Mistake

Using the any or interface{} when there needs to be expression for the value in question.

Fix

Replace any with structs or generics. Only consider it when we truly do not care what the data is like with json.Marshal(value any) ([]byte, error)

References

100 Go Mistakes

Being confused about nil and the empty slice

Mon, 01 Jan 0001 00:00:00 +0000

A slice is empty if it’s length is zero. A slice is nil if it is nil.

Mistake

Not being educated on the differences between the two.

Fix

A nil slice requires no allocation and because of this we should favor returning nil slices as a result

// if we don't know the length and the slice can be empty
var s []string
// another way to create a nil and empty slice that can be helpful
s := append([]int(nil), 42)
// If we know the future length
make([]string, length)
// Avoid this style unless we are initializing with elements
s := []string{}

References

100 Go Mistakes

Being confused about when to use generics

Mon, 01 Jan 0001 00:00:00 +0000

Generics in Go are types that can be specified later. Before generics were added to Go, handling similar functionality across types was a chore. With generics we can leverage the following builtin type constraints:

any
comparable

Or we can define a custom constraint:

type customConstraint interface {
 ~int | ~string // this constraint only supports ints and strings
}

int is a restriction to specifically an int while ~int supports all values whose underlying type is int

Being puzzled about channel size

Mon, 01 Jan 0001 00:00:00 +0000

An unbuffered channel, or a synchronous channel, has a size of zero and blocks. A buffered channel, or asynchronous channel, has some size and is unblocking until it becomes full.

For worker-pool patterns, the channel size should be the same as the number of workers. For rate-limiting, the channel size should be set in accordance to the resource we are limited by.

Outside of these use-cases, using a different channel size should be done with caution and should likely include a comment on the rationale behind that number. The smaller the value, the more CPU contention we can handle. The larger the number, the more memory we need to allocate.

Being puzzled about when to use channels or mutexes

Mon, 01 Jan 0001 00:00:00 +0000

In Go, channels are a communication mechanism that can be used to send and receive values. Channels can be either unbuffered, blocks until receiver is ready, or they can be buffered, blocks when the buffer is full.

For parallel goroutines, a mutex is necessary for synchronization. For coordination or communication, a channel is necessary.

References

100 Go Mistakes

Checking an error type inaccurately

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This stops working with wrapped errors

if err != nil {
 switch err := err.(type) {
 case transientError:
 http.Error(w, err.Error(), http.StatusServiceUnavailable)
 default:
 http.Error(w, err.Error(), http.StatusBadRequest)
 }
 return
}

Fix

Use the errors.As() function

if err != nil {
 if errors.As(err, &transientError{}){
 http.Error(w, err.Error(), http.StatusServiceUnavailable)
 } else {
 http.Error(w, err.Error(), http.StatusBadRequest)
 }
 return
}

References

100 Go Mistakes

Checking an error value inaccurately

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

if err == sql.ErrNoRows {

}

Fix

if errors.Is(err, sql.ErrNoRows) {

}

References

100 Go Mistakes

Common JSON handling mistakes

Mon, 01 Jan 0001 00:00:00 +0000

Type embedding

Mistake

This does not work because time.Time implements the json.Marshaler interface and will clobber any sort of JSON marshaling we are trying to accomplish.

type Event struct {
 ID int
 time.Time // embedded field
}

event := Event{
 ID: 123456,
 Time: time.Now(),
}

b, err := json.Marshal(event)
if err != nil {
 return err
}

Fix

type Event struct {
 ID: int
 Time: time.Time
}

Alternatively we could chose to implement the json.Marshaler interface

func (e *Event) MarshalJSON() ([]byte, error){
 return json.Marshal(
 // leveraging an anonymous struct
 struct {
 ID int
 Time time.Time
 }{
 ID: e.ID,
 Time: e.Time,
 },
 )
}

The monotonic clock

An OS handles two types of clocks:

Common SQL mistakes

Mon, 01 Jan 0001 00:00:00 +0000

sql.Open

Mistake

This does not always open the connection, it merely prepares it for later use.

db, err := sql.Open("mysql", dsn)
if err != nil {
 return err
}

Fix

db, err := sql.Open("mysql", dsn)
if err != nil {
 return err
}

err = db.Ping()
if err != nil {
 return err
}

Connection pooling

sql.Open doesn’t return a single connection, but a pool of connections. We can modify how this pool behaves with the following methods:

SetMaxOpenConns()
SetMaxIdleConns()
SetConnMaxIdleTime()
SetConnMaxLifetime()

Not using prepared statements

A prepared statement is a feature most SQL databases implement to execute a repeated SQL statement. This is in the interest of efficiency as well as it reduces the risk of SQL injections.

Comparing values incorrectly

Mon, 01 Jan 0001 00:00:00 +0000

Comparing values in Go, using == is not always appropriate.

Mistake

== and != do not work with slices and maps.

Fix

Consider using reflect.DeepEqual(), but keep in mind this is significantly slower than ==. If performance is critical, instead compare each element of the slice/map through iteration.

For testing solutions, consider external packages like go-cmp or testify.

References

100 Go Mistakes

Copying a sync type

Mon, 01 Jan 0001 00:00:00 +0000

All primitive types in the sync package follow one hard rule, they should never be copied.

sync.Cond
sync.Map
sync.Mutex
sync.RWMutex
sync.Once
sync.Pool
sync.WaitGroup

Mistake

This is an example of a data race from copying a sync primitive.

type Counter struct {
 mu sync.Mutex
 counters map[string]int
}

func NewCounter() Counter {
 return Counter{counters: map[string]int{}}
}

// The function receiver here is a value so it is copied instead of referenced
func (c Counter) Increment(name string){
 c.mu.Lock()
 defer c.mu.Unlock()

 c.counters[name]++
}

Fix

Alternatively, we could make Counter.mu a pointer to a sync.Mutex

Creating confusion with octal literals

Mon, 01 Jan 0001 00:00:00 +0000

Any integer literal in Go that begins with a 0 is considered to be an octal

Mistake

// This equals 108, not 110
sum := 100 + 010

Fix

Use the long form prefix 0o for describing octals

sum := 100 + 0o10

References

100 Go Mistakes

Creating data races with append

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This is a data race because the array is not full. Both goroutines will attempt to update the same index in the backing array.

s := make([]int, 0, 1)

go func() {
 s1 := append(s, 1)
}()

go func() {
 s2 := append(s, 1)
}()

Fix

Instead we can copy the slice and append to that.

s := make([]int, 0, 1)

go func() {
 sCopy := make([]int, len(s), cap(s))
 copy(sCopy, s)

 s1 := append(sCopy, 1)
}()

go func() {
 sCopy := make([]int, len(s), cap(s))
 copy(sCopy, s)

 s2 := append(sCopy, 1)
}()

References

100 Go Mistakes

Creating utility packages

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Creating any package named utils, common, or base is almost always a mistake. They become junk drawers for unrelated functions and provide no insight to what they provide.

Fix

Use specific names when naming packages and, if necessary, break up utility packages into smaller meaningful pieces.

References

100 Go Mistakes

Expecting deterministic behavior using select and channels

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Unlike the switch case, select case is random which case will be satisfied first. If messageCh is buffered, even if we had more messages to process on the messageCh when disconnectCh receives a message it becomes random which will be triggered.

for {
 select {
 case v := <-messageCh:
 fmt.Print(v)
 case <- disconnectCh:
 return
 }
}

///////////

for i := 0; i < 10; i++ {
 messageCh <- i
}

disconnectCh <- struct{}{}

Fix

Use an unbuffered channel so that it blocks and guarantees all messages are delivered. We could also use a single channel instead of two.

Forgetting about possible side effects with string formatting

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

func (c *Customer) String() string {
 c.mutex.RLock()
 defer c.mutex.RUnlock()
 return fmt.Sprintf("id %s, age %s", c.id, c.age)
}

func (c *Customer) UpdateAge(age int) error {
 c.mutex.Lock()
 defer c.mutex.Unlock()

 if age < 0 {
 // This creates a deadlock because it will be calling the String() method
 // through the Stringer interface
 return fmt.Errorf("age should be positive: %v", c)
 }

 c.age = age
 return nil
}

Fix

func (c *Customer) String() string {
 c.mutex.RLock()
 defer c.mutex.RUnlock()
 return fmt.Sprintf("id %s, age %s", c.id, c.age)
}

func (c *Customer) UpdateAge(age int) error {
 if age < 0 {
 return fmt.Errorf("age should be positive: %v", c)
 }

 c.mutex.Lock()
 defer c.mutex.Unlock()

 c.age = age
 return nil
}

References

100 Go Mistakes

Forgetting about sync.Cond

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This example works but contains a CPU burner loop. It wastes a lot of cycles checking if the donation goal has been met. This could be eliminated by using a shared channel between the two goroutines, but we introduce another problem where we could surpass our goal for one goroutine while the other goroutine is using that channel.

type Donation struct {
 mu sync.RWMutex
 balance int
}
donation := &Donation{}

f := func(goal int){
 donation.mu.RLock()
 for donation.balance < goal {
 donation.mu.RUnlock()
 donation.mu.RLock()
 }
 donation.mu.RUnlock()
}
go f(10)
go f(15)

go func(){
 for {
 time.Sleep(time.Second)
 donation.mu.Lock()
 donation.balance++
 donation.mu.Unlock()
 }
}()

Fix

type Donation struct {
 cond *sync.Cond
 balance int
}
donation := &Donation{
 cond: sync.NewCond(&sync.Mutex{}),
}

f := func(goal int){
 donation.cond.L.Lock()
 for donation.balance < goal {
 // blocks until condition is met/broadcast
 // cond.Wait() does the following:
 // - Unlock the mutex
 // - Suspend the goroutine until a notification is received
 // - Lock the mutex
 donation.cond.Wait()
 }
 donation.cond.L.Unlock()
}

go f(10)
go f(15)

for {
 time.Sleep(time.Second)
 donation.cond.L.Lock()
 donation.balance++
 donation.cond.L.Unlock()
 // broadcast that a condition was met
 donation.cond.Broadcast()
}

References

100 Go Mistakes

Forgetting the return after replying to an HTTP request

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

func handler(w http.ResponseWriter, req *http.Request) {
 err := foo(req)
 if err != nil {
 // this doesn't stop the function
 http.Error(w, "foo", http.StatusInternalServerError)
 }

 // ...
}

Fix

func handler(w http.ResponseWriter, req *http.Request) {
 err := foo(req)
 if err != nil {
 http.Error(w, "foo", http.StatusInternalServerError)
 return
 }

 // ...
}

References

100 Go Mistakes

Handling an error twice

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Logging an error in multiple places

Fix

Log or return an error, never do both.

References

100 Go Mistakes

Ignoring how arguments are evaluated in range loops

Mon, 01 Jan 0001 00:00:00 +0000

When using a range loop, the provide expression is evaluated once.

Mistake

a := [3]int{0, 1, 2}
for i, v := range a {
 a[2] = 10

 if i == 2 {
 fmt.Println(v) // this will print 2, not 10
 }
}

Fix

Don’t use the range variables if you are modifying the range expression.

a := [3]int{0, 1, 2}
for i := range a {
 a[2] = 10

 if i == 2 {
 fmt.Println(a[2]) // this will print 10
 }
}

References

100 Go Mistakes

Ignoring how defer arguments and receivers are evaluated

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

defer arguments are evaluated immediately. No matter what status is changed to it will always be an empty string for these two defer statements. The same holds true for function receivers.

func f() error {
 var status string
 defer notify(status)
 defer incrementCounter(status)
 // ...
}

Fix

Passing a pointer would allow mutations to the status variable to be reflected by defer. Using a pointer receiver would have the same effect.

func f() error {
 var status string
 defer notify(&status)
 defer incrementCounter(&status)
 // ...
}

References

100 Go Mistakes

Ignoring how the break statement works

Mon, 01 Jan 0001 00:00:00 +0000

A break statement is commonly used to terminate the execution of a loop.

Mistake

	for i := 0; i < 5; i++ {
		switch i {
		default:
		case 2:
			break // this will break the switch statement not the loop
		}
	}

Fix

Using a label

loop:
	for i := 0; i < 5; i++ {
		switch i {
		default:
		case 2:
			break loop
		}
	}

References

100 Go Mistakes

Ignoring package name collisions

Mon, 01 Jan 0001 00:00:00 +0000

Package name collisions occur when a variable or function shares the same name as a package.

Mistake

Package declaration

package redis

type Client struct {
	//...
}

func NewClient() *Client {
	//...
}

func (c *Client) Get(key string) (string, error) {
	// ...
}

Client implementation

redis := redis.NewClient()
v, err := redis.Get("foo")

The redis variable now makes the redis package inaccessible in this scope

Fix

Use an import alias or change the variable name.

References

100 Go Mistakes

Ignoring the fact that elements are copied in range loops

Mon, 01 Jan 0001 00:00:00 +0000

The range keyword is a convenient way to iterate over data structures.

Mistake

range performs a copy on all the elements of the data structure.

accounts := []account{
	{balance: 100.},
	{balance: 200.},
	{balance: 300.},
}

for _, a := range accounts {
	a.balance += 1000 // This will not modify the original slice
}

Fix

accounts := []account{
	{balance: 100.},
	{balance: 200.},
	{balance: 300.},
}

// using the index for the slice
for i := range accounts {
	accounts[i].balance += 1000 // This modifies the accounts object
}

// classic for loop
for i := 0; i < len(accounts); i++ {
	accounts[i].balance += 1000 // This modifies the accounts object
}

References

100 Go Mistakes

Ignoring the impact of using pointer elements in range loops

Mon, 01 Jan 0001 00:00:00 +0000

When not being careful, it’s possible to reference the wrong elements with range loops.

Mistake

Here we are referencing the range variable, customer, which will result in all elements of the customers slice being the same value.

func (s *Store) storeCustomers(customers []Customer) {
	for _, customer := range customers {
 // This pointer is to the range variable customer, not the customers slice
		s.m[customer.ID] = &customer
	}
}

Fix

func (s *Store) storeCustomers(customers []Customer) {
	for _, customer := range customers {
 // create a local variable first
 current := customer
		s.m[customer.ID] = &current
	}
}

References

100 Go Mistakes

Ignoring when to wrap an error

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Returning errors without context.

Fix

Wrap errors and provide context

if err != nil {
 return fmt.Errorf("bar failed: %w", err)
}

References

100 Go Mistakes

Inaccurate string iteration

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This does not print ê, but instead prints Ã and the length is printed to be 6 instead of 5. This is because the character ê requires 2 bytes to store.

s := "hêllo"

for i := range s {
 fmt.Printf("position %d: %c\n", i, s[i])
}

fmt.Printf("len=%d\n", len(s))

Fix

Use range variables

s := "hêllo"

for i, r := range s {
 fmt.Printf("position %d: %c\n", i, r)
}

Cast the string to a rune slice

s := "hêllo"
runes := []rune(s)

for i := range runes {
 fmt.Printf("position %d: %c\n", i, runes[i])
}

References

100 Go Mistakes

Inefficient map initialization

Mon, 01 Jan 0001 00:00:00 +0000

In Go a map is an unordered key value pair where all keys are distinct.

m := map[string]int {
 "one": 1,
 "two": 2,
 "three": 3,
}

Mistake

When a map grows, it doubles the number of buckets used to back it. This occurs when the average number of items in the buckets is greater than a constant value (6.5) or too many buckets have overflowed. When the map grows, all keys are dispatched again to all buckets which can become expensive with large maps.

Inefficient slice initialization

Mon, 01 Jan 0001 00:00:00 +0000

When initializing a slice using make we can provide a length and an optional capacity.

Mistake

Not giving a slice enough capacity when we know it will grow in size. In Go, a slice is resized by doubling it’s capacity and allocating a new backing array.

Fix

If we know a slice will grow substantially, we should give it enough capacity to minimize the number of allocations it will require.

Interface on the producer side

Mon, 01 Jan 0001 00:00:00 +0000

Deciding where to implement an interface is a pretty common mistake. An interface defined in the same package as the concrete implementation is referred to as the Producer Side. The Consumer Side is considered to be an interface defined in some external package where it is being used.

Mistake

Creating an interface on the producer side. Interfaces are satisfied implicitly in Go and because of this we should be trying to discover the abstraction, not create it. Creating an interface on the producer side means the producer is creating the abstraction for all it’s consumers.

Interface pollution

Mon, 01 Jan 0001 00:00:00 +0000

Interfaces are one of the most valuable tools for structuring Go code and as a result they are often abused creating unnecessary abstractions and difficult to follow code.

Creating interfaces and abstractions early. We should not be creating an interface before their is code to implement it. Abstractions should be discovered, not created.

Common behavior

Consider the sort interface which is incredibly common

type Interface interface {
	Len() int
	Less(i, j int) bool
	Swap(i, j int)
}

Decoupling

Coupled

type CustomerService struct {
	store mysql.Store
}

func (cs CustomerService) CreateNewCustomer(id string) error {
	customer := Customer{id: id}
	return cs.store.StoreCustomer(customer)
}

Decoupled using an interface

type customerStorer interface {
	StoreCustomer(Customer) error
}

type CustomerService struct {
	storer customerStorer
}

func (cs CustomerService) CreateNewCustomer(id string) error {
	customer := Customer{id: id}
	return cs.storer.StoreCustomer(customer)
}

Restricting Behavior

Concrete implementation

type IntConfig struct {
	// ...
}

func (c *IntConfig) Get() int {
	// Retrieve configuration
}

func (c *IntConfig) Set(value int) {
	// Update configuration
}

Restricted implementation using an interface

type intConfigGetter interface {
	Get() int
}

type Foo struct {
	threshold intConfigGetter
}

func NewFoo(threshold intConfigGetter) Foo {
	return Foo{threshold: threshold}
}

func (f Foo) Bar() {
	threshold := f.threshold.Get()
	// ...
}

References

100 Go Mistakes

Making wrong assumptions during map iterations

Mon, 01 Jan 0001 00:00:00 +0000

There are two primary misconceptions with map iterations in Go.

Mistake

Ordering

Order is not preserved in a map in Go. Iterating over a map multiple times will likely result in a unique ordering for each iteration.

Map insert during iteration

Updating a map’s contents during iteration is allowed, but can lead to unpredictable results. When a map entry is created during iteration, it may be produced during the iteration or skipped.

Maps and memory leaks

Mon, 01 Jan 0001 00:00:00 +0000

When maps grow and shrink, buckets need to be added to the underlying data structure to support it.

Mistake

When shrinking a map, the elements will be garbage collected, however the buckets will still remain.

Fix

Either create a new map and copy all the elements of the old map to it. This would result in a brief window of high memory consumption considering the two maps, but the old map would be eventually collected. Alternatively, make the values pointers. Pointers take up less memory and even though the buckets will still remain, there should be significantly less of them.

Missing code documentation

Mon, 01 Jan 0001 00:00:00 +0000

Every exported element should be documented.

Mistake

Having no documentation, or worse bad documentation

Fix

Documentation should be complete, punctuated sentences and should describe the intent, not the implementation.

Use the Deprecated: comment in documentation to indicate that this is deprecated. This is result in an LSP warning if it is being used.

Constants and variables should convey purpose and content though content can be just for internal purposes.

// DefaultPermission is the default permission used by the store engine.
const DefaultPermission = 0o644 // Need read and write accesses.

Packages should also provide some indicator to their scope. Keep the first line short and concise as it will appear in the godocs.

Misunderstanding Go contexts

Mon, 01 Jan 0001 00:00:00 +0000

A Context carries a deadline, a cancellation signal, and other values across API boundaries.

Deadline

A deadline is a specific point in time:

time.Duration
time.Time

If a deadline is met then any ongoing activities using that context should be stopped.

func (h publishHandler) publishPosition(position flight.Position) error {
 // context with a deadline of 4 seconds
 ctx, cancel := context.WithTimeout(context.Background(), 4*time.Second)
 defer cancel() // safeguard to cancel the context goroutine

 return h.pub.Publish(ctx, position)
}

Cancellation signals

func main() {
 ctx, cancel := context.WithCancel(context.Background())
 defer cancel() // this cancel signal gets called when main exits

 go func() {
 CreateFileWatcher(ctx, "foo.txt")
 }()
 // ...
}

Context values

Key value pairs can also be passed with a context

Misusing init functions

Mon, 01 Jan 0001 00:00:00 +0000

The init() function in go is a function that is initialized first in the package. The order of evaluation is

Constants and variables
Dependency init()s in alphabetical order
Main package init()
main()

Mistake

Error management in init() functions is limited since they do not return errors. The only way to indicate that something has gone wrong in an init() is to panic. This behavior should not be left to the package to decide whether to stop an application or not.

Misusing sync.WaitGroup

Mon, 01 Jan 0001 00:00:00 +0000

sync.WaitGroup is a mechanism to wait for n operations to complete.

Mistake

This is a data race, there is no guarantee that another goroutine will be started before the wg.Done() method is called causing the wg.Wait() to stop blocking.

wg := sync.WaitGroup{}
var v uint64

for i := 0; i < 3; i++ {
 go func(){
 wg.Add(1)
 atomic.AddUint64(&v, 1)
 wg.Done() // this is a data race
 }()
}
wg.Wait()

Fix

We can move the wg.Add(1) outside of the goroutine or alternatively we could call wg.Add(3) outside of the for loop.

Misusing trim functions

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

TrimRight removes all trailing runes in a given set.

fmt.Println(strings.TrimRight("123oxo", "xo")) // "123"

Fix

TrimSuffix removes a trailing suffix

fmt.Println(strings.TrimRight("123oxo", "xo")) // "123o"

References

100 Go Mistakes

Mixing up concurrency and parallelism

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Assuming the two are synonymous.

Fix

Parallelism is every part of a system being independent. Concurrency provides a structure to solve a problem with parts that may be parallelized.

References

100 Go Mistakes

Neglecting integer overflows

Mon, 01 Jan 0001 00:00:00 +0000

An integer overflow occurs when an arithmetic operation creates a value outside the range that can be represented in bytes. In Go an integer overflow or underflow is silent at run-time.

Mistake

var counter int32 = math.MaxInt32
counter++ // results in -2_147_483_648

Fix

func IncInt(counter int) int {
	if counter == math.MaxInt {
		panic("int overflow")
	}
	return counter + 1
}

func AddInt(a, b int) int {
	if a > math.MaxInt-b {
		panic("int overflow")
	}
	return a + b
}

func MultiplyInt(a, b int) int {
	// If one of the operands is equal to 0, it directly returns 0.
	if a == 0 || b == 0 {
		return 0
	}

	result := a * b

	if a == 1 || b == 1 {
		// Checks if one of the return result operands is equal to 1
		return result
	}

	if a == math.MinInt || b == math.MinInt {
		// Checks if one of the operands is equal to math.MinInt
		panic("integer overflow")
	}

	if result/b != a {
		// Checks if the multiplication
		panic("integer overflow")
		// leads to an integer overflow
	}

	return result
}

References

100 Go Mistakes

Never using named result parameters

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Name result parameters should be used when would provide better context.

type locator interface {
 getCoordinates(address string) (float32, float32, error)
}

Name result parameters should not be used when they provide no value

func ReadFull(r io.Reader, buf []byte) (n int, err error) {
 // ...
}

Fix

type locator interface {
 getCoordinates(address string) (lng, lat float32, error)
}

func ReadFull(r io.Reader, buf []byte) (int, error) {
 // ...
}

References

100 Go Mistakes

Not being aware of data alignment

Mon, 01 Jan 0001 00:00:00 +0000

Data alignment is the concept of having a variable’s memory address be a multiple of its size.

byte, uint8, int8: 1 byte
uint16, int16: 2 bytes
uint32, int32, float32: 4 bytes
uint64, int64, float64: 8 bytes
complex128: 16 bytes

For all of these examples, their memory address is guaranteed to be some multiple of their size. An int32 should have an address that is a multiple of 4.

Mistake

Since b1 is a byte and i is an int64, there is no way to align i with b1, so we must pad the struct with 7 bytes of data to meet the alignment of i. This means we are using 24 bytes of memory to store 10 bytes of data.

Not being aware of the possible problems with type embedding

Mon, 01 Jan 0001 00:00:00 +0000

In Go, a struct field is embedded if it is declared without a name

type Foo struct {
 Bar
}

type Bar struct {
 Baz int
}

foo := Foo{}
foo.Baz = 42

Mistake

Type embedding can sometimes expose fields and methods that outside sources should not have access to. Consider the Lock() and Unlock() methods.

Fix

Only embed when you are confident the methods that are promoted will not cause problems. Embedding is really just about convenience and if there is any doubt it is probably best to just manually promote behaviors.

Not being careful with goroutines and loop variables

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

s := []int{1, 2, 3}

for _, i := range s {
 go func() { // This is a closure and when it access `i` is not guaranteed
 fmt.Print(i)
 }()
}

Fix

s := []int{1, 2, 3}

for _, i := range s {
 // this variable is now local to each scope
 val := i
 go func() {
 fmt.Print(val)
 }()
}

s := []int{1, 2, 3}

for _, i := range s {
 // we pass the value as a parameter so it is evaluated immediately
 go func(val int) {
 fmt.Print(val)
 }(i)
}

References

100 Go Mistakes

Not categorizing tests

Mon, 01 Jan 0001 00:00:00 +0000

Build tags

//go:build integration

package db_test

go test --tags=integration -v .

Environment variables

This provides information to the user that this test was skipped

func TestInsert(t *testing.T) {
 if os.Getenv("INTEGRATION") != true {
 t.Skip("skipping integration test")
 }
}

Short mode

func TestLongRunning(t *testing.T){
 if testing.Short() {
 t.Skip("skipping long running test")
 }
}

go test -short -v .

References

100 Go Mistakes

Not closing transient resources

Mon, 01 Jan 0001 00:00:00 +0000

HTTP body

Mistake

type handler struct {
 client http.Client
 url string
}

func (h handler) getBody() (string, error) {
 // resp leaks here
 resp, err := h.client.Get(h.url)
 if err != nil {
 return "", err
 }

 body, err := io.ReadAll(resp.Body)
 if err != nil {
 return "", err
 }

 return string(body), nil
}

Fix

type handler struct {
 client http.Client
 url string
}

func (h handler) getBody() (string, error) {
 resp, err := h.client.Get(h.url)
 if err != nil {
 return "", err
 }

 defer func(){
 err := resp.Body.Close()
 if err != nil {
 // log
 }
 }()

 body, err := io.ReadAll(resp.Body)
 if err != nil {
 return "", err
 }

 return string(body), nil
}

sql.Rows

Mistake

// rows leaks here keeping an open connection
rows, err := db.Query("SELECT * FROM customers")
if err != nil {
 return err
}

// ...

return nil

Fix

rows, err := db.Query("SELECT * FROM customers")
if err != nil {
 return err
}

defer func(){
 err := rows.Close()
 if err != nil {
 // log
 }
}()
// ...

return nil

os.File

Mistake

This is fine for reading from a file, but for writing we want to capture any errors that may occur on the file close.

Not dealing with the time API efficiently

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Implementation

type Cache struct {
 mu sync.RWMutex
 events []Event
}

type Event struct {
 Timestamp time.Time
 Data string
}

func (c *Cache) TrimOlderThan(since time.Duration) {
 c.mu.Lock()
 defer c.mu.Unlock()

 // this is very difficult to test
 t := time.Now().Add(-since)
 for i := 0; i < len(c.events); i++ {
 if c.events[i].Timestamp.After(t) {
 c.events = c.events[i:]
 return
 }
 }
}

Test

func TestCache_TrimOlderThan(t *testing.T) {
 // if the machine becomes busy, we could easily miss this window
 events := []Event{
 {Timestamp: time.Now().Add(-20 * time.Millisecond)},
 {Timestamp: time.Now().Add(-10 * time.Millisecond)},
 {Timestamp: time.Now().Add(10 * time.Millisecond)},
 }

 cache := &Cache{}
 cache.Add(events)
 cache.TrimOlderThan(15 * time.Millisecond)
 got := cache.GetAll()
 want := 2

 if len(got) != want {
 t.Fatalf("want: %d, got: %d", want, len(got))
 }
}

Fix

Function type

type now func() time.Time

type Cache struct {
 mu sync.RWMutex
 events []Event
 now now
}

func NewCache() *Cache {
 return &Cache{
 events: make([]Event, 0),
 now: time.Now,
 }
}

// ...

func TestCache_TrimOlderThan(t *testing.T) {
 events := []Event{
 {Timestamp: parseTime(t, "2020-01-01T12:00:00.04Z")},
 {Timestamp: parseTime(t, "2020-01-01T12:00:00.05Z")},
 {Timestamp: parseTime(t, "2020-01-01T12:00:00.06Z")},
 }

 cache := &Cache{now: func() time.Time{
 return parseTime(t, "2020-01-01T12:00:00.06Z")
 }}
 cache.Add(events)
 cache.TrimOlderThan(15 * time.Millisecond)

 // ...

 func parseTime(t *testing.T, timestamp string) time.Time {
 // ...
 }
}

Even better is to remove the time.Duration from the parameter

Not enabling the -race flag

Mon, 01 Jan 0001 00:00:00 +0000

go test -race -v .

References

100 Go Mistakes

Not exploring all the Go test features

Mon, 01 Jan 0001 00:00:00 +0000

Code coverage

go test -coverpkg=./... -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Black box testing

package counter

package counter_test

Utility functions

func TestCustomer(t *testing.T) {
 customer := createCustomer(t, "foo")
 // ...
}

func createCustomer(t *testing.T, name string) Customer {
 // ...
 if err != nil {
 t.Fatal(err)
 }

 return customer
}

Setup and tear-down

Per function

func TestMySQLIntegration(t *testing.T) {
 // ...
 db := createConnection(t, "tcp(localhost:3306)/db")
 // ...
}

func createConnection(t *testing.T, dsn string) *sql.DB {
 db, err := sql.Open("mysql", dsn)
 if err != nil {
 t.FailNow()
 }

 t.Cleanup(
 func() {
 _ = db.Close()
 }
 )

 return db
}

Per package

func TestMain(m *testing.Main) {
 setupMySQL()
 code := m.Run()
 teardownMySQL()
 os.Exit(code)
}

References

100 Go Mistakes

Not handling an error

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Completely omitting the error.

notify()

Fix

Acknowledging that an error was returned, but we are ignoring it.

_ = notify()

References

100 Go Mistakes

Not handling defer errors

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Ignoring errors when using the defer keyword

type Closer interface {
 Close() error
}

func getBalance(db *sql.DB, clientID string) (float32, error) {
 rows, err := db.Query(query, clientID)

 if err != nil {
 return 0, err
 }

 // if this errors, it will not be reported
 defer rows.Close()

 // ...
}

Fix

Use some defer technique to ensure that the error is handled or acknowledged in some way.

type Closer interface {
 Close() error
}

func getBalance(db *sql.DB, clientID string) (float32, error) {
 rows, err := db.Query(query, clientID)

 if err != nil {
 return 0, err
 }

 defer func(){
 err := rows.Close()
 if err != nil {
 log.Printf("failed to close: %v", err)
 }
 }

 // ...
}

References

100 Go Mistakes

Not knowing how to reduce allocations

Mon, 01 Jan 0001 00:00:00 +0000

API changes

Mistake

Returning a slice is sharing up and causes the slice to escape the stack and get allocated on the heap.

type Reader interface {
 Read(n int) (p []byte, err error)
}

Fix

Passing the slice as a parameter is an example of sharing down and the slice is able to be allocated on the stack instead of the heap.

type Reader interface {
 Read(p []byte) (n int, err error)
}

Compiler optimizations

In the event we would want to create a map with a []byte key, we would write the following:

Not knowing which type of receiver to use

Mon, 01 Jan 0001 00:00:00 +0000

In Go, you can have either a pointer or a value receiver.

Mistake

This will not mutate the customer balance.

func (c customer) add(v float64) {
 c.balance += v
}

Fix

func (c *customer) add(v float64) {
 c.balance += v
}

Use pointer receivers for mutating an object. Use value receivers to keep an object immutable.

References

100 Go Mistakes

Not making slice copies correctly

Mon, 01 Jan 0001 00:00:00 +0000

The builtin copy function allows copying elements from one slice to another.

Mistake

The number of elements copied to the destination slice corresponds to the minimum value between the source slice length and the destination slice length. If the destination slice is an empty slice, then 0 elements will be copied.

Fix

Use a destination slice with a length equal to or greater than the source slice

src := []int{0, 1, 2}
dest := make([]int, len(src))
copy(dest, src)

The alternative append form which is more concise, but less obvious

Not properly checking if a slice is empty

Mon, 01 Jan 0001 00:00:00 +0000

What is the clear and concise method for checking if a slice has any elements?

Mistake

This handles the nil slice, but does not work for a slice with zero elements

if slice == nil {
 return
}

Fix

if len(slice) == 0 {
 return
}

References

100 Go Mistakes

Not relying on inlining

Mon, 01 Jan 0001 00:00:00 +0000

Inlining is replacing a function call with the body of the function, usually done automatically by the compiler. In Go, this can be observed by running go build -gcflags. This only works if the function falls within the inlining budget, otherwise the function is too complex to be inlined.

Inlining offers two benefits: removing the function call overhead and enabling more compiler optimizations. Mid-stack Inlining is inlining functions that call other functions. This is useful because it allows for fast-path inlining, distinguishing between fast and slow paths.

Not taking into account instruction-level parallelism

Mon, 01 Jan 0001 00:00:00 +0000

Instruction level parallelism (ILP) is performance optimization that allows the parallelization of a sequence of instructions. Instead of being a sum of the instructions total execution time, our total time is just the length of whichever instruction took the longest to execute.

This can be incredibly beneficial, but it can lead to hazards. If one of the instructions is dependent on another parallel instruction, like a conditional operation, this is called a control/branching hazard. CPU designers solved this problem using branch prediction. Using internal metrics, the CPU can make a best guess at what the most likely branching path will be. In the event that the CPU guesses incorrectly, the CPU will flush the current execution pipeline to ensure there are no inconsistencies leading to a performance penalty of ~10-20 cycles.

Not understanding CPU caches

Mon, 01 Jan 0001 00:00:00 +0000

CPU Architecture

Modern CPUs rely on caching to speed up memory access. In most cases there are three caching levels:

L1: ~1ns
- L1D: data
- L1I: instructions
L2: ~4ns
L3: ~10ns
Main Memory ~500-1,000ns

Additionally a CPU can be hyper-threaded, where a physical core is split into multiple logical cores (virtual cores). The L1 and L2 caches are on-die, meaning they are the same piece of silicon as the rest of the processor. The L3 cache is off-die, making it much slower than the L1 and L2.

Not understanding floating points

Mon, 01 Jan 0001 00:00:00 +0000

The concept of floating point numbers was created to solve the problem that integer values cannot represent fractional numbers. Floating point numbers are an approximation of real numbers due to the fact that their is an infinite number of fractions between two integers.

Mistake

Failing to understand the lack of precision with floating point numbers. Using conditional comparisons like == can result in unexpected behavior.

Fix

When comparing floating point numbers, check that the difference is within an acceptable range
When performing additions or subtractions, group operations with a similar order of magnitude for better accuracy.
to favor accuracy, if a sequence of operations requires addition, subtraction, multiplication, or division, perform the multiplication and division operations first.

References

100 Go Mistakes

Not understanding how the GC works

Mon, 01 Jan 0001 00:00:00 +0000

A GC keeps a tree of object references and the Go GC is based on the mark and sweep algorithm.

Mark stage: Traverse all objects on the heap and mark if they are in use
Sweep stage: Traverse the tree of reference from the root and deallocate objects that are no longer referenced

When a GC runs, it first performs a set of actions that lead to stopping the world. All available CPU time is used to perform the GC and the application is put on hold until the GC is finished. The Go GC also includes a way to free memory after consumption peak using a part of the GC called the periodic scavenger. After some time, the GC will detect that a large heap is no longer necessary and will free some of it to the OS. This can be done manually with debug.FreeOSMemory().

Not understanding race problems

Mon, 01 Jan 0001 00:00:00 +0000

Race problems can be among the hardest and most insidious bugs to fix.

Multiple goroutines data races

Mistake

i := 0

go func() {
 i++
}()

go func() {
 i++
}()

Fix

Using atomic operations

var i int64

go func() {
 atomic.AddInt64(&i, 1)
}()

go func() {
 atomic.AddInt64(&i, 1)
}()

Using mutexes

i := 0
mutex := sync.Mutex{}

go func() {
 mutex.Lock()
 i++
 mutex.Unlock()
}()

go func() {
 mutex.Lock()
 i++
 mutex.Unlock()
}()

Using channels

i := 0
ch := make(chan int)

go func() {
 ch <- 1
}()

go func() {
 ch <- 1
}()

i += <-ch
i += <-ch

Channel data races

Mistake

Synchronizing

i := 0
go func() {
 i++ // Racer
}()

fmt.Println(i) // Racer

Buffered channels

i := 0
ch := make(chan struct{}, 1) // buffered

go func() {
 i = 1
 <-ch // A buffered receive happens before a send
}()

ch <- struct{}{}
fmt.Println(i)

Fix

Synchronizing

i := 0
ch := make(chan struct{})

go func() {
 <-ch // this receive blocks until channel send
 fmt.Println(i)
}()

i++
// alternatively we could close this channel for the same effect
ch <- struct{}{} // channel send

Buffered channels

i := 0
ch := make(chan struct{}) // unbuffered

go func() {
 i = 1
 <-ch
}()

ch <- struct{}{}
fmt.Println(i)

References

100 Go Mistakes

Not understanding slice length and capacity

Mon, 01 Jan 0001 00:00:00 +0000

A slice is an array that can grow or shrink in size. In Go, a slice is backed by an array, and handles the logic of adding new elements if the backing array is full or shrinking it if it is almost empty.

Internally, a slice holds a pointer to the backing array and keeps track of a length and capacity. The length is the number of elements the slice contains, while the capacity is the number of elements in the backing array.

Not understanding stack vs heap

Mon, 01 Jan 0001 00:00:00 +0000

Stack

The stack is the default memory, a last in; first out (LIFO) data structure that stores all the local variables for a specific goroutine. When a goroutine is started it gets 2KB of contiguous memory as it’s stack space that can grow/shrink at run-time. Moving between different functions creates a new stack frame and allocates any variables necessary in that scope. Variables outside of the stack frame still exist, but cannot be referenced in the new frame without using a pointer.

Not understanding the concept of a rune

Mon, 01 Jan 0001 00:00:00 +0000

In Go, a rune is a Unicode code point.

Mistake

Believing that runes are always UTF8, this is false.

Fix

Runes can be any encoding.

References

100 Go Mistakes

Not understanding the concurrency impacts of a workload type

Mon, 01 Jan 0001 00:00:00 +0000

The execution time of a workload is limited by one of the following:

CPU speed: CPU bound
I/O speed: I/O bound
Available memory: Memory bound

Mistake

How do we parallelize this task?

func read(r io.Reader) (int, error) {
	count := 0

	for {
		b := make([]byte, 1024)
		_, err := r.Read(b)

		if err != nil {
			if err == io.EOF {
				break
			}
			return 0, err
		}

		count += task(b)
	}

	return count, nil
}

Fix

Worker-pooling pattern

func read(r io.Reader) (int, error) {
	var count int64
	wg := sync.WaitGroup{}

 // What we set `n` to largely is based on whether the task is IO or CPU bound
 // For I/O bound tasks, n should be some value that the system can handle.
 // Some trial and error may be necessary to determine this value.
 // For CPU bound tasks, use GOMAXPROCS:
 // n := runtime.GOMAXPROCS(0)
	var n = 10

 // Buffered channel and wait group are the same size
	ch := make(chan []byte, n)
	wg.Add(n)

 // Create n goroutines
	for i := 0; i < n; i++ {
		go func() {
			defer wg.Done()

			for b := range ch {
				v := task(b)
				atomic.AddInt64(&count, int64(v))
			}
		}()
	}

	for {
		b := make([]byte, 1024)
		// Read from r to b
		ch <- b
	}

	close(ch)
	wg.Wait()

	return int(count), nil
}

References

100 Go Mistakes

Not understanding the impacts of running Go in Docker and Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

It is important to understand the implications of running Go in Docker/Kubernetes to prevent common situations such as CPU throttling. The environment variable GOMAXPROCS defines the limit of OS threads in charge of executing user-level code simultaneously. This defaults to the number of OS logical CPU cores. Consider the following Kubernetes spec:

spec:
 containers:
 - name: app
 image: app
 resources:
 limits:
 cpu: 4000m # 4 CPU cores

We would expect GOMAXPROCS to have a value of 4, but in this case it doesn’t. It is set to 8 which is the number of cores on the host machine. With Kubernetes Completely Fair Scheduler (CFS) our pod is given a budget of CPU time. In this case, if we were using 8 threads at max capacity when our CPU resource limit was defined as 4 cores we would have our application throttled half the time. At the time this remains an open issue in Go, but can be solved with an import in main.go:

Not using errgroup

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This code correctly handles the aggregation of results with no data races, but has no solution for error handling.

func handler (ctx context.Context, circles []Circle) ([]Result, error) {
 results := make([]Result, len(circles))
 wg := sync.WaitGroup{}
 wg.Add(len(results))

 for i, circle := range circles {
 // variable shadowing to avoid data race
 i := i
 circle := circle

 go func() {
 defer wg.Done()

 result, err := foo(ctx, circle)
 if err != nil {
 // ??????
 }
 results[i] = result
 }()
 }

 wg.Wait()
}

Fix

func handle(ctx context.Context, circles []Circle) ([]Result, error) {
 results := make([]Result, len(circles))
 g, ctx := errgroup.WithContext(ctx)

 for i, circle := range circles {
 i := i
 circle := circle

 g.Go(func() error {
 result, err := foo(ctx, circle)
 if err != nil {
 return err
 }

 results[i] = result
 return nil
 })
 }

 err := g.Wait()
 if err != nil {
 return nil, err
 }

 return results, nil
}

References

100 Go Mistakes

Not using Go diagnostic tools

Mon, 01 Jan 0001 00:00:00 +0000

Profiling

The following profiles can be collected from the go profiler, pprof:

CPU: where the application spends its time
Goroutine: stack traces of the ongoing goroutines
Heap: heap memory allocations to monitor usage and check for leaks
Mutex: lock contentions to see mutex behavior and check if we are spending too much time in locking calls
Block: where goroutines block waiting on sync primitives

Enabling pprof

We can expose the data using the net/http/pprof package at the url http://localhost/debug/pprof. This can even be used in production. The profiles that impact performance are active for just short periods and must be enabled by default.

Not using linters

Mon, 01 Jan 0001 00:00:00 +0000

A linter is an automated tool for analyzing code and catching errors. Just having a linter active in your code editor will catch a variety of mistakes like variable shadowing.

Mistake

Not using a linter.

Fix

Use a linter or have code linted by CI.

References

100 Go Mistakes

Not using nil channels

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

In this version, ch1 blocks ch2 until ch1 is closed. This would be a problem if ch1 stays open forever.

func merge(ch1, ch2 <-chan int) <-chan int {
 ch := make(chan int, 1)

 go func() {
 for v := range ch1 {
 ch <- v
 }

 for v := range ch2 {
 ch <- v
 }
 close(ch)
 }()

 return ch
}

Fix

Make the channel nil when it is no longer open

func merge(ch1, ch2 <- chan int) <-chan int {
 ch := make(chan int, 1)

 go func(){
 for ch1 != nil || ch2 != nil {
 select {
 case v, open := <-ch1:
 if !open {
 ch1 = nil
 break
 }
 ch <- v
 case v, open := <-ch2:
 if !open {
 ch2 = nil
 break
 }
 ch <- v
 }
 }
 close(ch)
 }()

 return ch
}

References

100 Go Mistakes

Not using notification channels

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This is 1 byte of storage

notification := make(chan bool)

Fix

This takes zero bytes of storage

notification := make(chan struct{})

References

100 Go Mistakes

Not using table driven tests

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

func removeNewLineSuffixes(s string string{
 if s == "" {
 return s
 }

 if strings.HasSuffix(s, "\r\n") {
 return removeNewLineSuffixes(s[:len(s)-2])
 }

 if strings.HasSuffix(s, "\n") {
 return removeNewLineSuffixes(s[:len(s)-1])
 }

 return s
}

func TestRemoveNewLineSuffix_Empty(t *testing.T) {
 got := removeNewLineSuffixes("")
 expected := ""
 if got != expected {
 t.Errorf("got: %s", got)
 }
}

func TestRemoveLineSuffixes_CRNL(t *testing.T) {
 got := removeNewLineSuffixes("a\r\n")
 expected := "a"
 if got != expected {
 t.Errorf("got: %s", got)
 }
}

func TestRemoveLineSuffixes_NL(t *testing.T) {
 got := removeNewLineSuffixes("a\n")
 expected := "a"
 if got != expected {
 t.Errorf("got: %s", got)
 }
}

Fix

func TestRemoveNewLineSuffix(t *testing.T) {
 tests := map[string]struct{
 input string
 want string
 }{
 "empty": {
 input: "",
 want: "",
 },
 "crnl": {
 input: "a\r\n",
 want: "a",
 },
 "nl": {
 input: "a\n",
 want: "a",
 },
 }

 for name, tt := range tests {
 t.Run(name, func(t *testing.T) {
 got := removeNewLineSuffixes(tt.input)
 if got != tt.want {
 t.Errorf("got: %s, want: %s", got, tt.want)
 }
 })
 }
}

We can also make these sub-tests run in parallel

Not using test execution modes

Mon, 01 Jan 0001 00:00:00 +0000

Parallel

Parallel execution mode allows us to run specific tests in parallel. These tests will run alongside other parallel tests. Any sequential tests will be executed first.

func TestFoo(t *testing.T){
 t.Parallel()
}

Shuffle

Randomize the execution order.

go test -shuffle=on -v .

References

100 Go Mistakes

Not using testing utility packages

Mon, 01 Jan 0001 00:00:00 +0000

References

100 Go Mistakes

Not using the functional options pattern

Mon, 01 Jan 0001 00:00:00 +0000

For API design, how do we handle optional configurations?

Mistake

Using struct parameters or complicated builders to handle optional configurations.

type Config struct {
	Port int
}

func NewServer(addr string, cfg Config) {
	// ...
}

// Initializes Port to 0
c1 := httplib.Config{
	Port: 0,
}

// Port is missing, so it’s initialized to 0.
c2 := httplib.Config{
}

Fix

Leverage closures and variadic arguments

type options struct {
	port *int // we make this a pointer so that it can be nil
}

// A function type that updates the options struct
type Option func(options *options) error

func WithPort(port int) Option {
	return func(options *options) error {
		if port < 0 {
			return errors.New("port should be positive")
		}

		options.port = &port

		return nil
	}
}

// Accepts many option closures
func NewServer(addr string, opts ...Option) (*http.Server, error) {
	// we create the options struct that the closures reference
	var options options

	for _, opt := range opts {
		err := opt(&options)
		if err != nil {
			return nil, err
		}
	}

	// At this stage, the options struct is built and contains the config
	// Therefore, we can implement our logic related to port configuration
	var port int
	if options.port == nil {
		port = defaultHTTPPort
	} else {
		if *options.port == 0 {
			port = randomPort()
		} else {
			port = *options.port
		}
	}
	// ...
}

References

100 Go Mistakes

Overusing getters and setters

Mon, 01 Jan 0001 00:00:00 +0000

Data encapsulation refers to hiding the values and state of an object. Getters and Setters are a means to enable encapsulation, yet Go has no automatic support for getters or setters.

Mistake

Providing a getter/setter for all struct attributes when it clearly is not necessary.

Fix

Use getters/setters for the following use cases:

Encapsulating behavior for a field (validation, calculated value)
Hiding internal representation (this should rarely be considered)
Aid in debugging

References

100 Go Mistakes

Panicking

Mon, 01 Jan 0001 00:00:00 +0000

Once a panic is triggered, it continues up the call stack until either the current goroutine has returned or panic is caught with recover.

Mistake

Panicking any time an error occurs is a mistake.

Fix

Only panic when a programming error has occurred to signal that this mistake is a bug and not a runtime error.

References

100 Go Mistakes

Project disorganization

Mon, 01 Jan 0001 00:00:00 +0000

Organizing a project in Go can be challenging. There is no enforced structure or schema which can lead to code bases that are difficult to navigate.

Mistake

Having no plan on how a project should be organized.

Fix

There a many solutions for how to layout a project that all depend on the use case.

Flat

For small projects it’s usually fine to just have a flat layout. There is no need to over-complicate things.

Propagating an inappropriate context

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This creates a race condition between the two internal requests

func handler(w http.ResponseWriter, w *http.Request) {
 response, err := doSomeTask(r.Context(), r)
 if err != nil {
 http.Error(w, err.Error(), http.StatusInternalServerError)
 return
 }

 go func() {
 err := publish(r.Context(), response) // this is a race condition
 // error handling
 }()

 writeResponse(response)
}

Fix

// We wrap the context and implement the Context interface
type detach struct {
 ctx context.Context
}

func (d detach) Deadline() (time.Time, bool) {
 return time.Time{}, false
}

func (d detach) Done() <-chan struct{} {
 return nil
}

func (d detach) Err() error {
 return nil
}

func (d detach) Value(key any) any {
 return d.ctx.Value(key)
}

func handler(w http.ResponseWriter, w *http.Request) {
 response, err := doSomeTask(r.Context(), r)
 if err != nil {
 http.Error(w, err.Error(), http.StatusInternalServerError)
 return
 }

 go func() {
 // Wrapping this detaches the cancellation signal while preserving the
 // original Values
 err := publish(detach{r.Context()}, response)
 // error handling
 }()

 writeResponse(response)
}

References

100 Go Mistakes

Providing a wrong time duration

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

It is not obvious when this ticker will go off. We would assume every second, but in fact it is ever microsecond.

ticker := time.NewTicker(1000)
for {
 select {
 case <-ticker.C:
 // tick
 }
}

Fix

Using the time durations provided from the time package we can be certain how this ticker works.

ticker := time.NewTicker(time.Second)
for {
 select {
 case <-ticker.C:
 // tock
 }
}

References

100 Go Mistakes

Returning a nil receiver

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Nil is a valid receiver in Go.

type MultiError struct {
 errs []string
}

func (m *MultiError) Add(err error) {
 m.errs = append(m.errs, err.Error())
}

// Satisfying the error interface
func (m *MultiError) Error() string {
 return strings.Join(m.errs, ";")
}

func (c Customer) Validate() error {
 var m *MultiError

 if c.Age < 0 {
 m = &MultiError{}
 m.Add(errors.New("age is negative"))
 }

 if c.Name == "" {
 if m == nil {
 m = &MultiError{}
 }

 m.Add(errors.New("name is nil"))
 }

 // Even though m is nil, it is still a valid receiver.
 // This will always return as an error
 return m
}

Fix

func (c Customer) Validate() error {
 var m *MultiError

 if c.Age < 0 {
 m = &MultiError{}
 m.Add(errors.New("age is negative"))
 }

 if c.Name == "" {
 if m == nil {
 m = &MultiError{}
 }

 m.Add(errors.New("name is nil"))
 }

 return nil
}

References

100 Go Mistakes

Returning interfaces

Mon, 01 Jan 0001 00:00:00 +0000

Returning an interface can result in dependency and import cycle hell.

Mistake

Returning an interface

Fix

Return structs and accept interfaces if at all possible. There are very few edge cases where this makes sense and it should always be heavily scrutinized.

References

100 Go Mistakes

Sleeping in unit tests

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Implementation

type Handler struct {
 n int
 publisher publisher
}

type publisher interface {
 Publish([]Foo)
}

func (h Handler) getBestFoo(someInputs int) Foo {
 foos := getFoos(someInputs)
 best := foos[0]

 go func() {
 if len(foos) > h.n {
 foos = foos[:h.n]
 }

 h.publisher.Publish(foos)
 }()

 return best
}

Test

type publisherMock struct {
 mu sync.RWMutex
 got []Foo
}

func (p *publisherMock) Publish(got []Foo){
 p.mu.Lock()
 defer p.mu.Unlock()

 p.got = got
}

func (p *publisherMock) Get() []Foo {
 p.mu.Lock()
 defer p.mu.Unlock()

 return p.got
}

func TestGetBestFoo(t *testing.T) {
 mock := publisherMock{}
 h := Handler{
 publisher: &mock,
 n: 2,
 }

 foo := h.getBestFoo(42)

 // this is very flaky, there is no guarantee this will be enough time
 time.Sleep(10 * time.Millisecond)

 published := mock.Get()
}

Fix

Use channels

Slices and memory leaks

Mon, 01 Jan 0001 00:00:00 +0000

Slicing an existing slice can lead to memory leaks under certain conditions.

Leaking capacity

Mistake

func getMessageType(msg []byte) []byte {
 return msg[:5] // This makes a slice with the same capacity as msg
}

Fix

func getMessageType(msg []byte) []byte {
 msgType := make([]byte, 5)
 copy(msgType, msg)
 return msgType
}

Slices and pointers

When working with slices, if the element is a pointer or a struct with pointer fields, it will not be collected by the garbage collector.

Either make a copy of the slice to remove unwanted elements or set the remaining slices to nil.

Starting a goroutine without knowing when to stop it

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

It is unclear when this goroutine will stop. The channel implementation in foo() is unknown. If this never closes then it is a leak.

ch := foo()

go func(){
 for v := range ch {
 // ...
 }
}()

Fix

We instead should be signaling resources letting them know it is time to close

func main() {
 w := newWatcher()
 defer w.close()

 // ...
}

func newWatcher() watcher {
 w := watcher{}
 go w.watch()

 return w
}

func (w watcher) close(){
 // close resource
}

References

100 Go Mistakes

Substrings and memory leaks

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

uuid := log[:36] // slices the string, but keeps the backing array

Fix

uuid := string([]byte(log[:36])) // copies the sub-string into a []byte
uuid := strings.Clone(log[:36]) // creates a new copy of the string

References

100 Go Mistakes

Thinking concurrency is always faster

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Assuming that a concurrent solution is always faster than a sequential one. If the workload we are parallelizing is too small, the overhead of creating and scheduling goroutines quickly becomes the bottle-neck.

Fix

Create a hybrid approach that only leverages goroutines when the elements being processed exceeds some threshold.

References

100 Go Mistakes

time.After and memory leaks

Mon, 01 Jan 0001 00:00:00 +0000

time.After(time.Duration) is the concurrent alternative for time.Sleep(time.duration).

Mistake

This would result in creating a new time.After instance that is not release until the timer expires for every iteration of this loop/every message received.

func consumer(ch <-chan Event) {
 for {
 select {
 case event := <-ch:
 // ...
 case <-time.After(time.Hour):
 // ...
 }
 }
}

Fix

This is better, but creating a new context every loop is still not great.

func consumer(ch <-chan Event) {
 for {
 ctx, cancel := context.WithTimeout(context.Background(), time.Hour)
 select {
 case event := <-ch:
 cancel()
 // ...
 case <-ctx.Done():
 // ...
 }
 }
}

The more appropriate approach would be to use a timer.

Under-optimized string concatenation

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This allocates a new string for each loop. This is due to a string being immutable in Go.

func concat(values []string) string {
 s := ""
 for _, value := range values {
 s += value
 }
 return s
}

Fix

func concat(values []string) string {
	total := 0
	// Get total number of bytes
	for i := 0; i < len(values); i++ {
		total += len(values[i])
	}

	sb := strings.Builder{}
	sb.Grow(total)
	for _, value := range values {
		_, _ = sb.WriteString(value)
	}

	return sb.String()
}

References

100 Go Mistakes

Unexpected side effects of using slice append

Mon, 01 Jan 0001 00:00:00 +0000

When slicing another slice, the newly created slice will have a pointer referencing the backing array of the original slice. This means that any modifications to either slice will be reflected in both.

Mistake

When appending contents to either slice that will not fit inside the backing array, a new backing array must be created. This breaks the relationship between the two slices.

Fix

Create a copy of the original slice to avoid this behavior.

Unintended side effects with named result parameters

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Under normal circumstances, this code would not compile because we never set nor initialize the err variable. However, since it is a named result parameter the err variable is initialized to it’s zero value and as a result err always returns nil.

func (l loc) getCoordinates(ctx context.Context, address string) (lat, lng float32, err error) {
 isValid := l.validateAddress(address)

 if !isValid {
 return 0, 0, errors.New("invalid address")
 }

 if ctx.Err() != nil {
 return 0, 0, err
 }
}

Fix

Either avoid named result parameters or shadow the err variable.

func (l loc) getCoordinates(ctx context.Context, address string) (lat, lng float32, err error) {
 isValid := l.validateAddress(address)

 if !isValid {
 return 0, 0, errors.New("invalid address")
 }

 err := ctx.Err()
 if err != nil {
 return 0, 0, err
 }
}

References

100 Go Mistakes

Unnecessary Nested Code

Mon, 01 Jan 0001 00:00:00 +0000

Multiple layers of nested code can impact readability.

Mistake

In this case, the client looks as if it is being assigned, but it is just the shadow variable that is being set.

func join(s1, s2 string, max int) (string, error) {
	if s1 == "" {
		return "", errors.New("s1 is empty")
	} else {
		if s2 == "" {
			return "", errors.New("s2 is empty")
		} else {
			// Calls a concatenate function to perform some specific concatenation but may return errors
			concat, err := concatenate(s1, s2)
			if err != nil {
				return "", err
			} else {
				if len(concat) > max {
					return concat[:max], nil
				} else {
					return concat, nil
				}
			}
		}
	}
}

Fix

Same functionality, but easier to follow

Useless string conversions

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Converting strings to []byte slice when it doesn’t make sense. While strings are human friendly, []byte slices is what most functions accept as a parameter.

Fix

Use []byte slice and the relevant transforms in the bytes package.

References

100 Go Mistakes

Using a defer inside a loop

Mon, 01 Jan 0001 00:00:00 +0000

The defer statement delays execution until the surrounding function exits.

Mistake

These files could potentially be kept open forever, causing a leak.

func readFiles(ch <-chan string) error {
	for path := range ch {
		file, err := os.Open(path)

		if err != nil {
			return err
		}

		// This is deferred when readFiles exits, not the current iteration
		defer file.Close()
	}

	return nil
}

Fix

Change the function scope

func readFiles(ch <-chan string) error {
	for path := range ch {
 readFile(path)
	}

	return nil
}

func readFile(path string) error {
 file, err := os.Open(path)

 if err != nil {
 return err
 }

 defer file.Close()
}

References

100 Go Mistakes

Using a filename as a function input

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

Testing this function would require a unique file for every use case.

func countEmptyLinesInFile(filename string) (int, error) {
 file, err := os.Open(filename)
 if err != nil {
 return 0, err
 }
 // Handle file closure
 scanner := bufio.NewScanner(file)
 for scanner.Scan() {
 // ...
 }
}

Fix

Extract the file i/o from the function logic.

func countEmptyLines(reader io.Reader) (int, error) {
 scanner := bufio.NewScanner(reader)
 for scanner.Scan() {
 // ...
 }
}

References

100 Go Mistakes

Using mutexes inaccurately with slices and maps

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This creates a data race. Internally a map is a runtime.hmap struct containing mostly metadata and a pointer referencing the actual data. The same holds true for slices

type Cache struct {
 mu sync.RWMutex
 balances map[string]float64
}

func (c *Cache) AddBalance(id string, balance float64) {
 c.mu.Lock()
 c.balances[id] = balance
 c.mu.Unlock()
}

func (c *Cache) AverageBalance() float64 {
 c.mu.RLock()
 // this does not copy the data, just a pointer to the data
 balances := c.balances
 c.mu.RUnlock()

 sum := 0
 for _, balance := range balances {
 sum += balance
 }

 return sum / float64(len(balances))
}

Fix

Alternatively, we could make a deep copy of the map/slice by iterating over all of it’s elements and inserting them into a new copy.

Using the default HTTP client and server

Mon, 01 Jan 0001 00:00:00 +0000

Client

Mistake

This does not specify any timeouts

client := &http.Client{}

Fix

client := &http.Client{
 Timeout: 5 * time.Second,
 Transport: &http.Transport{
 DialContext: (&net.Dialer{
 Timeout: time.Second,
 }).DialContext,
 TLSHandshakeTimeout: time.Second,
 ResponseHeaderTimeout: time.Second,
 },
}

We should also consider that the clients are pooled and re-used. Balancing these variables is critical for production facing systems.

http.Transport.IdleConnTimeout (default 90s): this is how long idle connections hang around before closed
http.Transport.MaxIdleConns (default 100): the max idle connections
http.Transport.MaxIdleConnsPerHost (default 2): max idle connections per host

Server

Mistake

server := &http.Server{}
server.Serve(listener)

Fix

server := &http.Server{
 Addr: ":8080",
 ReadHeaderTimeout: 500 * time.Millisecond,
 ReadTimeout: 500 * time.Millisecond,
 Handler: http.TimeoutHandler(handler, time.Second, "foo"),
 IdleTimeout: time.Second,
}

References

100 Go Mistakes

Variable shadowing

Mon, 01 Jan 0001 00:00:00 +0000

Variable shadowing is re-declaring a variable in an inner block and can result in unexpected outcomes.

Mistake

In this case, the client looks as if it is being assigned, but it is just the shadow variable that is being set.

var client *http.Client
if tracing {
 // Shadowed client
	client, err := NewTracingClient()
	if err != nil {
	 return err
	}
} else {
 // Shadowed client
	client, err := NewClient()
	if err != nil {
	 return err
	}
}
// Client is still nil at this point

Fix

In this case, a temporary variable is being declared and then is assigned to the client

Writing concurrent code that leads to false sharing

Mon, 01 Jan 0001 00:00:00 +0000

Mistake

This example works from a concurrency perspective, but it is in example of false sharing and can result in poor performance. Since sumA and sumB are allocated contiguously, they more than likely will be placed on the same block. When the these goroutines end up getting scheduled to different cores, the CPU will need to copy this block of memory twice. Due to cache coherency, even though each goroutine is only modifying it’s respective sum, the CPU only tracks the cache line.

Writing inaccurate benchmarks

Mon, 01 Jan 0001 00:00:00 +0000

Not resetting or pausing the timer

func BenchmarkFoo(b *testing.B) {
 setup()
 b.ResetTimer()
 for i := 0; i < b.N; i++ {
 foo()
 }
}

func BenchmarkFoo(b *testing.B) {
 for i := 0; i < b.N; i++ {
 b.StopTimer()
 setup()
 b.StartTimer()
 foo()
 }
}

Micro-benchmarks

func BenchmarkAtomicStoreInt32(b *testing.B) {
 var v int32
 for i := 0; i < b.N; i++{
 atomic.StoreInt32(&v, 1)
 }
}

func BenchmarkAtomicStoreInt64(b *testing.B) {
 var v int64
 for i := 0; i < b.N; i++ {
 atomic.StoreInt64(&v, 1)
 }
}

Run the benchmark multiple times and evaluate statistics using benchstat

go test -bench=. -count=10 | stats.txt
benchstat stats.txt

Compiler optimizations

This function is likely to be in-lined, making the benchmark useless

const m1 = 0x5555555555555555
const m2 = 0x3333333333333333
const m4 = 0x0f0f0f0f0f0f0f0f
const h01 = 0x0101010101010101

func popcnt(x uint64) uint64 {
 x -= (x >> 1) & m1
 x = (x & m2) + ((x >> 2) & m2)
 x = (x + (x >> 4)) & m4
 return (x * h01) >> 56
}

We can avoid in-lining by forcing the function to write to a local variable and then write to a variable outside of the function scope.