Go

Idiomatic Go

Write Go that is boring in the best way - direct, predictable, obvious on the first read. Clear is better than clever. The common failure mode (and the LLM default) is importing Java/Spring habits - deep layer trees, generic repositories, heavy frameworks, manual worker pools - into a language built for flat, simple, discoverable APIs. When in doubt, delete the abstraction.

Core principles

Clear is better than clever. If a function's control flow takes three reads to follow, rewrite it. Keep the happy path un-indented: handle errors and edge cases first and return.

func GetUser(id string) (*User, error) {
    user, err := db.FindUser(id)
    if err != nil {
        return nil, fmt.Errorf("finding user %s: %w", id, err)
    }
    return user, nil // happy path stays at the left margin
}

Make the zero value useful. Design types so the zero value works without a constructor - sync.Mutex and bytes.Buffer are the gold standard.

type Counter struct {
    mu    sync.Mutex // usable at the zero value - no New() needed
    count int
}

func (c *Counter) Inc() { c.mu.Lock(); c.count++; c.mu.Unlock() }

Packages: flat, named for what they do

Start flat; add a package only when a domain earns a namespace. Name packages by what they do (auth, billing, jobs), never by what layer they are (service, repository, controller) - layer-named packages breed circular imports and interface bloat and add zero clarity in Go. No utils/, helpers/, or common/ junk drawers; they signal unclear ownership. Packages don't import each other sideways - cycles mean wrong boundaries; the composition root wires them.

In this repo: code lives under internal/ in a deliberate domain (pure interfaces) / infra (adapters) / services (business logic) split, wired by a DI container (internal/container/container.go). That is this project's structure - follow it; don't "flatten internal/." spf13's transferable rules still hold: name by purpose, no junk-drawer packages, wire at the composition root (here, the container).

Interfaces: discovered, not designed

Write concrete types first. Introduce an interface only when a consumer genuinely needs to swap implementations, and define it in the consuming package, kept small (io.Reader, not *os.File). Accept interfaces, return structs - callers get the narrow dependency they need without type-asserting to reach real fields.

// the consumer declares exactly what it needs; the concrete store needn't know
type UserFetcher interface {
    GetUser(id string) (*User, error)
}

type Processor struct{ fetcher UserFetcher }

In this repo: domain contracts are centralized in internal/domain/interfaces.go so counterfeiter can generate fakes from one place - that's the established seam. Still prefer small interfaces; just declare new ones there when they need a generated mock.

Errors are values

Check them explicitly; they aren't exceptions. Wrap with %w to add context while preserving the chain for errors.Is / errors.As. Combine siblings with errors.Join (Go 1.20) - no multierr needed.

data, err := os.ReadFile(path)
if err != nil {
    return fmt.Errorf("loading config %s: %w", path, err)
}

Functional options for complex construction

When a type has many optional settings, avoid telescoping constructors:

type Option func(*Server)

func WithTimeout(d time.Duration) Option { return func(s *Server) { s.timeout = d } }

func NewServer(addr string, opts ...Option) *Server {
    s := &Server{addr: addr, timeout: 30 * time.Second} // sane defaults
    for _, opt := range opts {
        opt(s)
    }
    return s
}

Testing is just Go

Go testing is just Go programming - reach for the stdlib testing package, not a BDD framework.

• Table-driven tests with t.Run subtests are the standard.
• Call t.Helper() in assertion helpers so failures point at the case, not the helper.
• Prefer simple fakes/stubs for stand-ins - implicit interfaces make them cheap to hand-write.
• Put fixtures in testdata/ (the tool ignores it); diff large output against golden files.
• Compare structs with github.com/google/go-cmp/cmp, not reflect.DeepEqual.
• Abstract the filesystem with afero and inject afero.NewMemMapFs() in tests.

func TestParse(t *testing.T) {
    tests := []struct {
        name    string
        in      string
        wantErr bool
    }{
        {"valid", "port=8080", false},
        {"bad", "port=abc", true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            _, err := Parse(tt.in)
            if (err != nil) != tt.wantErr {
                t.Fatalf("Parse(%q) err = %v, wantErr %v", tt.in, err, tt.wantErr)
            }
        })
    }
}

In this repo: fakes for domain interfaces are counterfeiter-generated under tests/mocks/, not hand-written. Regenerate with task mocks:generate (pre-commit runs it when internal/domain/interfaces.go changes); for a new domain interface, add a counterfeiter line under mocks:generate in Taskfile.yml. Use the generated fakes - don't hand-roll rivals. Table tests, testdata, and go-cmp still apply.