Idioms and Gotchas

Patterns and pitfalls every Go codebase hits. Results appear in the same fence: same-line // comments when short, multiline // blocks below the sample when not.

Accept Interfaces

Functions accept interfaces, return concrete types.

// func Save(s Store) error

Copy on Return

Copy slices before returning internal state.

// out := make([]T, len(in)); copy(out, in); return out

Loop Variable

Go 1.22+ per-iteration vars.

// for _, v := range xs { go f(v) } // ok in 1.22+

Nil Slice JSON

nil slice encodes null; empty encodes [].

b, _ := json.Marshal([]int(nil))
string(b)  // "null"

Goroutine Leak

Always provide an exit path.

// select { case <-ctx.Done(): return; case ch <- v: }

Defer in Loop

defer runs at function end - wrap loop bodies.

// for ... { func(){ defer f.Close(); ... }() }

Functional Options

Optional config via options.

// type Option func(*Server)

Wire Timeouts

Always set HTTP client/server timeouts.

// &http.Client{Timeout: 10 * time.Second}

Dont Panic API

Return error from public APIs.

// if id == "" { return fmt.Errorf("id required") }

Context Param

Pass ctx into methods each call.

// func (s *Svc) Get(ctx context.Context, id string)

Mutex No Copy

Never copy a Mutex - share by pointer.

// type S struct { mu sync.Mutex }

Map Range Order

Map iteration order is randomized.

// do not rely on map range order

Retry Idempotent

Retry only idempotent ops with backoff.

// if temporary(err) { sleep; retry }

go generate

Codegen as a first-class step.

// //go:generate mockgen ...

Errors Not Strings

Branch with errors.Is/As, not string contains.

// errors.Is(err, ErrNotFound)

Related

• Concurrency Goroutines - leak prevention
• Interfaces and Generics - interface design
• Error Handling - error idioms

External Related Links

• Effective Go - Official guide to writing clear, idiomatic Go.
• Go Wiki – Learn - Curated community learning resources.
• Stack Overflow – Go Tag - Q&A for Go programming.
• Learning Go (2nd Edition) - Jon Bodner.
• Concurrency in Go - Katherine Cox-Buday.

Stack versions: Go 1.26.x · chi/gin/echo latest (verify at build)