Go — Best Practices & Patterns

Go is a language of constraints: explicit error handling, a minimal type system, no generics-style ceremony for many years, and a concurrency model built around goroutines and channels. Those constraints are features. They force teams toward readable, maintainable, and predictable code — but only when the team agrees on conventions.

This guide distills production-tested Go best practices: how to lay out a project, name things consistently, handle errors without drowning in boilerplate, design interfaces that are small and composable, use concurrency safely, write useful tests, log observably, and keep performance predictable. The patterns here are drawn from the Go Proverbs, the standard library, and real-world codebases that ship at scale.

These rules are heuristics, not absolute laws. They cover the most common sources of review friction: error handling, interface size, goroutine lifetimes, package naming, and mutation of shared state. Internalizing them will make your Go code idiomatic and safer by default.

Go does not enforce a project layout, but the Go community has converged on a few patterns. For services and CLIs, the Standard Go Project Layout is the most common starting point. It separates binaries, libraries, internal packages, configuration, deployments, and test helpers.

The internal/ directory is enforced by the compiler: packages inside it can only be imported by code within the module tree. Use internal/ for application-specific code that should not become a public API surface. Place reusable, stable packages under pkg/ only if external projects genuinely need to import them.

Each program in cmd/ should be a thin wrapper around packages from internal/ or pkg/. The main function is responsible for reading configuration, wiring dependencies, handling OS signals, and reporting fatal errors. It should contain almost no business logic.

Naming in Go is intentionally terse. The language relies on package names to provide context, so identifiers inside a package can be short. Clarity is measured by how well a name reads at the call site, not by how descriptive it is in isolation.

Go's explicit error handling is a feature, not a bug. Every function that can fail returns an error. The caller decides whether to handle, wrap, or propagate. The key discipline is to add context at every layer so that the eventual log entry tells a complete story.

Wrap errors with fmt.Errorf("...: %w", ...) when crossing package boundaries or significant abstraction layers. Use errors.Is to check against sentinels and errors.As to extract typed errors. Never compare error strings directly in production code.

Custom error types are useful when the caller needs more than a string. Keep them simple and document the intended use of errors.As. Avoid deep error hierarchies — Go is not Java, and checked exceptions do not exist.

Go interfaces are satisfied implicitly. This is one of the language's most powerful features, but it only works well when interfaces are small. Large interfaces create tight coupling and make testing difficult. The standard library models this perfectly: io.Reader has one method.

Define interfaces on the consumer side, not the producer side. If a package needs something that can read bytes, it should define interface { Read([]byte) (int, error) } rather than importing a broad interface from elsewhere. This keeps packages loosely coupled and mocks trivial.

Accept interfaces, return concrete types. A function signature should ask for the smallest surface area it needs and return the most useful concrete value it can. This maximizes flexibility for callers while keeping implementations simple.

Go makes concurrency easy to start and hard to get right. Goroutines are cheap, but their lifetimes must be managed. Channels are elegant, but shared memory is often simpler when ownership is clear. The Go Proverbs capture the philosophy: "Do not communicate by sharing memory; share memory by communicating."

Always pass context.Context as the first argument to functions that may run in goroutines. Use sync.WaitGroup to wait for goroutines, and close channels only from the sender side. If any worker fails, cancel siblings promptly to avoid wasted work.

Use mutexes for protecting shared state, but keep the critical sections small. Prefer sync.RWMutex when reads dominate. Never call out to network or disk inside a mutex, and never hold a lock while sending on a channel — that invites deadlocks.

Go's built-in testing package is intentionally minimal. Table-driven tests are the dominant pattern. They keep related cases together, make adding new scenarios easy, and provide a clear structure for setup, execution, and assertion.

Use t.Run with named subtests for clarity. Keep helpers in the same file if they are specific, or place reusable helpers in a testutil package under internal/. Use t.Helper() so failure lines point to the actual test case.

For integration tests, use t.Cleanup and test fixtures. Mark slow tests with -short guards so developers can run a fast subset locally. Keep unit tests fast and deterministic; integration tests can be slower but must still clean up after themselves.

Logging is your primary observability tool in production. Go provides log in the standard library, and since Go 1.21, log/slog provides structured logging. Structured logs are easier to query, aggregate, and alert on than free-form strings.

Pass a logger through your application rather than relying on the global default. Inject *slog.Logger into constructors. This makes tests quiet and lets different subsystems run at different log levels. Avoid logging sensitive fields like tokens, passwords, or PII.

Use log levels intentionally. Debug for fine-grained tracing during development, Info for normal lifecycle events, Warn for recoverable issues, and Error for failures that require attention. Reserve Fatal and Panic for program startup only.

Go is fast by default, but performance pitfalls still exist: unnecessary allocations, goroutine leaks, large interface conversions, and contention on hot paths. The first rule is to measure. Use benchmarks, profiling, and tracing before optimizing.

Prefer sync.Pool for short-lived, allocation-heavy objects on hot paths. Preallocate slices when the final size is known. Use strings.Builder for repeated string concatenation. Avoid boxing values into interface in tight loops.

For HTTP services, set reasonable timeouts on every server and client. Go's default HTTP server has no timeouts, which makes it vulnerable to slowloris and idle-connection leaks. Always configure ReadTimeout, WriteTimeout, and IdleTimeout.

Use this checklist for every Go pull request. Many checks can be automated with go vet, staticcheck, and CI. Reserve human review for design decisions, error-message quality, and concurrency safety.

Every Go developer hits the same traps eventually. Knowing them in advance saves hours of debugging. Here are the most frequent sources of subtle bugs and how to avoid them.

Interface nils surprise newcomers because an interface value is a tuple of (type, value). A nil concrete value inside a non-nil interface is still non-nil. For slices, understand when operations share backing arrays and copy explicitly when needed. Always consider ctx.Done() in long-running operations.

Go's toolchain is one of its strengths. Mastering the standard tools and a few well-chosen third-party tools will make you far more productive than chasing the latest library trends.

These references are the authoritative sources behind the recommendations in this guide. They are worth revisiting as the language and ecosystem evolve.