Golang

Go Best Practices

Production patterns from Google, Uber, and the Go team. Updated for Go 1.25.

Sub-skills: skills/go-error-handling, skills/go-concurrency, skills/go-testing, skills/go-performance, skills/go-code-review, skills/go-linting, skills/go-project-layout, skills/go-security. Deep-dive references in references/.

Core Principles

Readable code prioritizes these attributes in order:

1. Clarity: purpose and rationale are obvious to the reader
2. Simplicity: accomplishes the goal in the simplest way
3. Concision: high signal to noise ratio
4. Maintainability: easy to modify correctly
5. Consistency: matches surrounding codebase

Error Handling

Full guide: skills/go-error-handling/SKILL.md | Reference: references/error-handling.md

• Return errors, never panic in production code
• Wrap with `%w` when callers need errors.Is/errors.As; use %v at boundaries
• Keep context succinct: "new store: %w" not "failed to create new store: %w"
• Handle errors once: don't log and return the same error
• Error strings: lowercase, no punctuation
• Indent error flow: handle errors first, keep happy path at minimal indentation
• Use `errors.Join` (Go 1.20+) for multiple independent failures
• Sentinel errors: Err prefix for vars, Error suffix for types

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

Concurrency

Full guide: skills/go-concurrency/SKILL.md | Reference: references/concurrency.md

• Channel size: 0 (unbuffered) or 1; anything else needs justification
• Document goroutine lifetimes: when and how they exit
• Use `errgroup.Group` over manual sync.WaitGroup for error-returning goroutines
• Prefer synchronous functions: let callers add concurrency
• Zero value mutexes: don't use pointers; don't embed in public structs
• Typed atomics (Go 1.19+): atomic.Int64, atomic.Bool, atomic.Pointer[T]
• `sync.Map` (Go 1.24+): significantly improved performance for disjoint key sets

g, ctx := errgroup.WithContext(ctx)
g.SetLimit(10)
for _, item := range items {
    g.Go(func() error { return process(ctx, item) })
}
return g.Wait()

Naming

• MixedCaps always: never underscores (MaxLength not MAX_LENGTH)
• Initialisms: consistent case (URL, ID, HTTP not Url, Id, Http)
• Short variables: scope determines length (i for loops, DefaultTimeout for globals)
• Receiver names: 1-2 letter abbreviation, consistent across methods, never this/self
• Package names: lowercase single word, no util/common/misc
• No repetition: http.Serve not http.HTTPServe; c.WriteTo not c.WriteConfigTo

Pointer vs Value Receivers

Imports

import (
    "context"
    "fmt"

    "github.com/google/uuid"
    "golang.org/x/sync/errgroup"

    "yourcompany/internal/config"
)

• Three groups: stdlib, external, internal (separated by blank lines)
• Rename only to avoid collisions
• No dot imports except test files with circular deps
• Blank imports (import _ "pkg") only in main or tests

Module Management (Go 1.24+)

Track tool dependencies in go.mod with tool directives:

tool (
    golang.org/x/tools/cmd/stringer
    github.com/golangci/golangci-lint/cmd/golangci-lint
)

go get -tool golang.org/x/tools/cmd/stringer  # add
go tool stringer -type=Status                  # run
go get tool                                    # update all
go install tool                                # install to GOBIN

Structs

• Always use field names in initialization (positional breaks on changes)
• Omit zero value fields
• Don't embed types in public structs (exposes API unintentionally)
• Use `var` for zero value structs: var user User

Slices and Maps

• Nil slices preferred: var t []string (use []string{} only for JSON [] encoding)
• Copy at boundaries: copy() or maps.Clone() to prevent mutation
• Preallocate: make([]T, 0, len(input)) when size is known
• Use `slices` and `maps` packages: slices.Sort, slices.Clone, maps.Clone, maps.Equal

Generics (Go 1.18+)

• Use when writing identical code for different types
• Use cmp.Ordered or custom constraints for type safety
• Generic type aliases (Go 1.24+): type Set[T comparable] = map[T]struct{}
• Don't over-generalize: use concrete types or interfaces when they suffice

func Filter[T any](s []T, pred func(T) bool) []T {
    result := make([]T, 0, len(s))
    for _, v := range s {
        if pred(v) {
            result = append(result, v)
        }
    }
    return result
}

Iterators (Go 1.23+)

Range over functions for custom iterators:

func Backward[T any](s []T) func(yield func(int, T) bool) {
    return func(yield func(int, T) bool) {
        for i := len(s) - 1; i >= 0; i-- {
            if !yield(i, s[i]) {
                return
            }
        }
    }
}

for i, v := range Backward(items) {
    fmt.Println(i, v)
}

String/bytes iterators (Go 1.24+): strings.Lines, strings.SplitSeq, strings.SplitAfterSeq

Structured Logging (Go 1.21+)

slog.Info("user created", "id", userID, "email", email)
slog.With("service", "auth").Info("starting")
handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})

• slog.DiscardHandler (Go 1.24+) for suppressing logs in tests
• Use consistent key names, group related fields with slog.Group

Performance

Full guide: skills/go-performance/SKILL.md | Reference: references/performance.md

• `strconv` over `fmt`: strconv.Itoa(n) not fmt.Sprintf("%d", n)
• Avoid repeated `[]byte` conversions: store once, reuse
• Preallocate map capacity: make(map[string]int, len(items))
• `strings.Builder` with Grow() for concatenation

Testing

Full guide: skills/go-testing/SKILL.md | Reference: references/testing.md

• Table-driven tests with t.Parallel() for subtests
• `go-cmp` over reflect.DeepEqual for clear diff output
• Useful failure messages: include input, got, want
• `t.Fatal` for setup failures
• Interfaces belong to consumers, not producers
• `T.Context` and `T.Chdir` (Go 1.24+)
• `b.Loop()` (Go 1.24+): cleaner benchmarks, no b.ResetTimer() needed
• `synctest.Test` (Go 1.25+): deterministic concurrent testing with synthetic time

Resource Management (Go 1.24+)

• `runtime.AddCleanup`: multiple cleanups per object, no cycle leaks (replaces SetFinalizer)
• `weak.Pointer[T]`: weak references for caches, canonicalization, observers
• `os.Root`: scoped file access preventing path traversal attacks

Patterns

Full reference: references/patterns.md

• Functional options: WithTimeout(d), WithLogger(l) for configurable constructors
• Interface compliance: var _ http.Handler = (*Handler)(nil)
• Defer for cleanup: small overhead, worth the safety
• Graceful shutdown: signal handling + srv.Shutdown(ctx)
• Enums start at one: zero = invalid/unset
• Use `time.Duration`: never raw ints for time
• Two-value type assertions: t, ok := i.(string) to avoid panics
• Context first: func Process(ctx context.Context, ...)
• Avoid mutable globals: use dependency injection
• Avoid `init()`: prefer explicit initialization in main
• `//go:embed` (Go 1.16+): embed static files
• Field tags: explicit json:"name" on marshaled structs
• Container-aware GOMAXPROCS (Go 1.25+): automatic cgroup-based tuning

Common Gotchas