aeondave/golang-patterns

Go Patterns

This skill focuses on idiomatic Go design and code review guidance.

If your task is primarily measurement/profiling/optimization, use golang-performance.

When to activate

• Writing new Go code (packages, APIs, services)
• Reviewing PRs for idioms, readability, and maintainability
• Refactoring for cleaner error handling and smaller interfaces
• Designing concurrency flows with cancellation and backpressure

---

Core principles (high signal)

• gofmt is non-negotiable. Style debates end at gofmt.
• Prefer clarity: small functions, early returns, explicit control flow.
• Make the zero value useful.
• Keep interfaces small; define them where they’re consumed.
• Handle errors explicitly; wrap with context; avoid panic for control flow.
• Concurrency should be bounded and cancellable; avoid goroutine leaks.

---

Outcome expectations

• Public APIs are small, explicit, and boring to maintain.
• Error handling is consistent and machine-checkable with errors.Is/As.
• Concurrency flows always have cancellation and backpressure.
• Tooling baseline (gofmt, tests, vet/race) is easy to run in CI.

---

Recommended workflow

1. Define package boundary + API contracts (inputs, outputs, errors) first.
2. Implement with small functions and explicit control flow.
3. Add context propagation and cancellation checks on blocking operations.
4. Run formatting/tests/vet/race before review.
5. Review for leaks, hidden globals, and interface over-abstraction.

---

Quick review checklist

• Naming: MixedCaps for exported, no underscores, packages short and lower-case
• Errors: fmt.Errorf("context: %w", err), errors.Is/As used correctly
• Context: ctx is first param; cancellation propagates; no context.Context stored in structs
• Interfaces: accept interfaces, return concrete types; no “kitchen-sink” interfaces
• Concurrency: goroutines have a stop condition; channels are closed by senders; backpressure exists
• Tooling: go test ./..., go test -race ./..., go vet ./...

---

Common anti-patterns to reject

• Storing context.Context in structs
• Unbounded goroutine fan-out in request paths
• Catch-all interfaces like Doer, Manager, Service without clear boundary
• Returning wrapped errors without enough domain context
• Package-level mutable state hidden behind helper functions

---

Resources

Load on demand (progressive disclosure):

• references/effective-go.md — distilled Effective Go + Code Review Comments pointers
• references/errors.md — wrapping, sentinel vs typed errors, validation, retryable errors
• references/interfaces.md — interface placement, design patterns, optional behavior
• references/concurrency.md — cancellation, errgroup, leaks, worker pools, backpressure
• references/api-and-structs.md — receiver rules, functional options, embedding
• references/package-layout.md — project layout, package naming, dependency injection
• references/tooling.md — gofmt/goimports, vet, staticcheck, golangci-lint guidance