go

Go

Project structure

• go.mod at repo root. Module path matches repo URL: module github.com/org/repo
• Pin Go version in go.mod: go 1.25. Toolchain auto-selects via toolchain directive
• Tool dependencies via go.mod tool directives (1.24+). go get -tool golang.org/x/tools/cmd/stringer
• Standard layout: cmd/ for binaries, internal/ for private packages, pkg/ only if genuinely public
• No circular imports. internal/ enforces package boundaries
• go.sum committed. Never manually edited

Errors

• Errors are values. Return error as last return value
• Wrap with context: fmt.Errorf("op failed: %w", err). Always %w, not %v, when caller may inspect
• Sentinel errors: var ErrNotFound = errors.New("not found"). Use errors.Is to check, not ==
• Custom error types: implement Error() string. Use errors.As to extract
• Never ignore errors. _ = f() only with explicit justification in comment
• No panic in library code. Reserve for truly unrecoverable states in main
• Check errors immediately after call. No deferred error checks buried in logic

Interfaces

• Define interfaces at point of use (consumer), not point of implementation
• Small interfaces. Prefer single-method interfaces: io.Reader, io.Writer
• Accept interfaces, return concrete types
• No interface for a single implementation unless testing or future extensibility is clear
• interface{} → any (Go 1.18+). Use any everywhere
• Embed interfaces to compose: type ReadWriter interface { Reader; Writer }

Generics

• Use generics to eliminate identical logic across types. Not for premature abstraction
• Constrain tightly: [T int | int64] over [T any] when type matters
• comparable constraint for map keys and equality checks
• golang.org/x/exp/slices and maps patterns now in stdlib (slices, maps packages, 1.21+)
• Range over func iterators (1.22+): use iter.Seq and iter.Seq2 for custom iterables
• Generic type aliases fully supported (1.24+): type Set[T comparable] = map[T]struct{}