Go Style Guide

Go Style Guide Skill

This skill defines practical Go coding style and engineering patterns optimized for:

• humans reading/maintaining code
• coding agents generating/restructuring code reliably
• production readiness (correctness, testability, performance)

Use this skill anytime you are working with Go: new code, refactors, reviews, and architecture decisions.

TL;DR

• Design for testability first; inject dependencies and keep logic pure.
• Prefer Config in → concrete struct out; validate and default in constructors.
• Errors are contracts: sentinel errors + %w or errors.Join.
• Keep packages reusable: no hidden globals, no default logging.
• Benchmark hot paths before claiming wins.
• Return concrete types; accept interfaces at boundaries.
• Keep main.go thin; app wiring lives in app/.

House Style Disclaimer

This is intentionally opinionated. It favors consistency and long-term maintainability over accommodating every Go style preference.

Quick Rules Table

Common Pitfalls

• Returning interfaces by default instead of concrete types.
• Logging in reusable packages instead of returning errors.
• Passing global app config through packages rather than local Config.
• Hiding dependencies behind package-level globals.
• Over-structuring directory layouts in small projects.
• Shipping changes that claim performance wins without benchmarks.

Core Principles

1. Testability is first-class

• Prefer designs that are easy to test without booting an entire application.
• Inject dependencies explicitly.
• Keep pure logic isolated.

2. Config-driven construction

• Prefer Config in → struct out constructors.
• Validate at construction.
• Default explicitly.

3. Errors are a contract

• Prefer sentinel errors where practical, especially in packages.
• Use %w (or errors.Join) so callers can use errors.Is/As.

4. Benchmark what matters

• Add benchmarks for performance-sensitive code paths.
• Avoid “it’s faster” claims without go test -bench.

5. Packages are reusable by default

• Keep packages domain-focused and individually testable.
• Avoid global state and hidden side effects.

Package Types

App package (orchestrator)

Owns:

• dependency wiring (DB, clients, loggers)
• lifecycle (start/stop)
• error policy (retry, ignore, crash)
• logging and metrics policy

Non-app packages (reusable units)

Rules:

• No direct logging (see references/LOGGING.md)
• Return errors, don’t hide them
• Define a local Config/Opts contract
• Accept initialized dependencies (DB/client/etc), do not create them internally

Directory Structure

Services / apps

• cmd/<appname>/main.go for entrypoints
• Keep main.go thin: parse config, wire dependencies, call app.Run(ctx, cfg)

Example:

cmd/myapp/main.go
pkg/...
pkg/app/...

Libraries

• Packages at top-level directories, or under pkg/ if it improves clarity for newcomers.
• Avoid junk drawers (utils, common) unless they truly represent a domain.

Constructors and Config

Preferred constructor shape

• New(cfg Config) (*T, error) or Dial(cfg Config) (*T, error)
• Validate + default inside constructor
• Return a concrete type by default

Interfaces: yes, when they pay rent

Interfaces improve testability, but don’t return interfaces by default.

Prefer:

• accept interfaces at boundaries (dependency injection)
• return concrete types, unless there is a clear multi-impl boundary or you must hide implementation

Canonical Config Example (Generic Executor)

This is the “accepted” pattern: Config drives behavior, constructor returns a concrete struct, and test seams are explicit.

// Runner provides a minimal contract for executing work.
type Runner interface {
    Run(ctx context.Context, input []byte) ([]byte, error)
}

// Config configures behavior and dependencies.
type Config struct {
    Timeout time.Duration
    Runner  Runner
}

// executor implements Runner-backed execution.
type executor struct {
    cfg  Config
    run  Runner
}

Guidance:

• Config is owned by the package (not passed around as global app config)
• Defaults apply in New (e.g., timeout, Runner)
• Validate at construction when possible

Logging

Logging is owned by the application.

If a package must log (rare async/network/runtime cases), inject *slog.Logger via Config, default to discard, and keep structured logs.

See: references/LOGGING.md

Errors

Prefer sentinel errors in packages

• Export var ErrX = errors.New("...") for stable meaning
• Wrap with %w or use errors.Join so errors.Is works

Rules:

• Don’t use %s to wrap errors (it breaks unwrap semantics)
• Add context with wrapping: fmt.Errorf("doing X: %w", err)

File Organization and Efficiency

Go file layout (practical default)

Within a package:

1. package comment (if primary file)
2. imports
3. constants / vars
4. types (interfaces + structs)
5. constructors
6. methods
7. functions (helpers last)

Avoid catch-all buckets like types.go, constants.go, util.go unless strongly justified.

Struct field efficiency

• Keep hot-path structs compact where it matters
• Consider field ordering to reduce padding (especially large arrays, bools, pointers)
• But do not micro-optimize without benchmarks

Benchmarks

Add benchmarks for:

• serialization/deserialization
• hot-path functions
• concurrency primitives and contention paths
• adapters/wrappers in tight loops

Benchmark rules:

• Use b.ReportAllocs()
• Include realistic inputs
• Compare alternatives if proposing a change

Top-level Interfaces + Implementations

A preferred pattern:

• define a small boundary interface in a top-level package
• provide implementations in subpackages (drivers/, backends/, etc.)
• keep contracts small and stable

Use when:

• multiple implementations exist (real + mock, or multiple backends)
• it clarifies architecture and enables testing

Reference Index

Use these supporting documents when deeper detail is needed:

• references/LOGGING.md Logging rules: default “no logging in packages,” exceptions, slog injection.

• references/ERRORS.md Sentinel-first error design, wrapping rules, errors.Is/As contracts.

• references/CONFIG.md Canonical Config struct patterns, constructor validation + defaults.

• references/INTERFACES.md Interface boundaries, driver patterns, testability-first design.

• references/LAYOUT.md File organization, struct field efficiency, package naming guidance.

• references/BENCHMARKS.md Benchmark expectations, templates, performance validation rules.

• references/REVIEW-CHECKLIST.md PR review rubric for humans and coding agents.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.