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

Full reference: references/gotchas.md

Linting

Full guide: skills/go-linting/SKILL.md

• Use golangci-lint as the standard linter aggregator
• Recommended linters: errcheck, govet, staticcheck, revive, gosimple, goimports, errorlint, bodyclose
• Add as a tool dependency (Go 1.24+): go get -tool github.com/golangci/golangci-lint/cmd/golangci-lint
• Run in CI: use golangci/golangci-lint-action for GitHub Actions
• Suppress sparingly: prefer fixing over //nolint comments

Project Layout

Full guide: skills/go-project-layout/SKILL.md

• cmd/: one subdirectory per executable, keep main.go thin
• internal/: private packages, enforced by the Go toolchain
• Avoid pkg/, src/, models/, utils/: name packages by purpose
• Flat is fine: small projects should not have deep directory trees
• Dockerfile: multi-stage build, CGO_ENABLED=0, distroless base image

Security

Full guide: skills/go-security/SKILL.md

• Parameterized SQL queries: never interpolate user input
• os.Root (Go 1.24+): scoped file access preventing path traversal
• Validate at boundaries: decode into typed structs, validate fields
• Never hardcode or log secrets: use Secret type with redacted String()
• Standard crypto only: crypto/rand for random bytes, bcrypt for passwords
• HTTP timeouts: always set ReadTimeout, WriteTimeout, IdleTimeout
• govulncheck: scan dependencies for known vulnerabilities
• go test -race: always run with the race detector in CI

Experimental (Go 1.25)

• encoding/json/v2: enable with GOEXPERIMENT=jsonv2. Better performance, streaming, custom marshalers per call.

Documentation

• Comments are full sentences starting with the declared name
• Package comments: before package declaration, no blank line

References

1. Google Go Style Guide
2. Uber Go Style Guide
3. Effective Go
4. Go Code Review Comments
5. Go 1.23 Release Notes
6. Go 1.24 Release Notes
7. Go 1.25 Release Notes