language-go

Go

Errors are values

• Return error; do not panic across package boundaries.
• Wrap with fmt.Errorf("doing X: %w", err) to preserve the chain.
• Inspect with errors.Is and errors.As. Never string-match messages.
• Sentinel errors (var ErrNotFound = errors.New(...)) for expected cases; typed errors when callers need structured data.

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

Interfaces — small, defined by the consumer

• Define interfaces in the package that uses them, not where concrete types live.
• Single-method interfaces are normal (io.Reader, io.Closer).
• Accept interfaces, return concrete types.

Concurrency

• A goroutine without a known termination path is a leak. Always know who stops it.
• context.Context plumbs cancellation and deadlines — first parameter, named ctx.
• Channels for ownership transfer; mutexes for protecting state. A sync.Mutex is often simpler than a goroutine.
• errgroup.Group for structured concurrency with error propagation.

g, ctx := errgroup.WithContext(ctx)
for _, job := range jobs {
    job := job
    g.Go(func() error { return process(ctx, job) })
}
if err := g.Wait(); err != nil { return err }

Context rules

• ctx is the first parameter of any blocking or IO function.
• Never store context.Context in a struct field.
• Don't use context.Value for required parameters — only cross-cutting concerns like request IDs.

Code generation

• A // Code generated ... DO NOT EDIT. header means the file is output, not source. Never hand-edit it — edits are clobbered on the next run and drift from their input.
• Edit the generator's input, then regenerate with go generate ./... (or the tool directly). Commit the regenerated file with the source change.
• Applies to stringer, mockgen, sqlc, protoc-gen-go, and google/wire.

google/wire — detected by a wire.go tagged //go:build wireinject plus a wire_gen.go carrying the Wire DO NOT EDIT. header. To change dependency injection:

• Edit provider sets / injectors in wire.go only — never wire_gen.go.
• Regenerate with go generate ./... (or wire ./...), then stage the updated wire_gen.go. If go generate ./... produces no diff, wire.go likely lacks a //go:generate wire directive — run wire ./... directly.