Go Rules & Best Practices Summary

Cross-cutting rule index linking every checklist on the site.

These rules distill the go-rules section and point to specialized checklists for concurrency, modules, security, and performance.

How to Use This List

• New contributors: start with Go Rules Quickstart, then Tier A here.
• Library authors: enforce Tier A + B before tagging v1.x.
• Service teams: add Tier C before production launch.
• Link this page from CONTRIBUTING and PR templates as the rule index.

A - Foundational idioms

• Treat Effective Go as the narrative baseline. Community checklists operationalize it; do not fork stale copies.
• Automate gofmt, goimports, vet, and tests in CI. Objective rules should never depend on reviewer memory.
• Check every error return at boundaries. Libraries return; applications translate to logs and exit codes once.
• Wrap errors with %w when callers inspect sentinels. Opaque messages break errors.Is chains.
• Use short names in small scopes and descriptive exported names. Scope length drives naming, per Effective Go.
• Document every exported symbol with godoc. Exported APIs are semver contracts for libraries.
• Walk the Effective Go Rules Checklist during onboarding. Twenty-five items cover daily idioms.

B - API, modules, and dependencies

• Put context.Context first on IO and RPC functions. Name it ctx; never store context in structs.
• Accept interfaces, return concrete types. Consumers define small interfaces; producers return structs.
• Use internal/ for non-public packages. Compiler enforcement beats "do not import" comments.
• Run go mod tidy on every module change. Commit go.sum diffs atomically with imports.
• Tag library releases with semver. Breaking changes require major bumps or /v2 paths.
• Keep direct dependencies minimal and owned. Run go mod why -m on new requires.
• Apply API Design Rules for Go Libraries before widening exports.
• Apply Module & Dependency Rules on platform audits.

C - Concurrency, security, and performance

• Give every goroutine an exit path tied to context or WaitGroup. Leaks surface as shutdown hangs and OOM.
• Assign one owner to close each channel. Receivers never close; document ownership in types.
• Run go test -race on packages that use goroutines or shared maps. Race failures block merge.
• Use Concurrency Rules Checklist for worker pools and streaming handlers.
• Validate external input at HTTP/gRPC boundaries. Parameterized SQL, size limits, and safe templates.
• Keep secrets out of source, logs, and client-facing errors. Load from orchestrator secrets at runtime.
• Run govulncheck when dependencies change. Triage reachable CVEs with upgrade or dated acceptance.
• Apply Security Rules for Go Services before launch gates.
• Profile before optimization PRs merge. Attach CPU or alloc evidence to claims of speedup.
• Default to clear code; optimize only proven hot paths. Record exceptions with benchmarks.
• Follow Performance Rules: When to Optimize for SLO work.

D - Review culture and living standards

• Pair rules with Code Review Standards for Go Teams. Lint is floor; review is ceiling.
• Promote a repeated review nit into linter or ADR. Rules should shrink debate surface over time.
• Re-audit rules after Go minor upgrades. New vet checks and go fix modernizers change enforcement.
• Tier library vs service strictness explicitly. Published modules stay conservative on exports.
• Link PR templates to this index. Authors self-check before requesting review.

FAQs

Related

• Effective Go as a Living Standard - section explainer
• Go Rules Quickstart - runnable intro
• Effective Go Rules Checklist - twenty-five core idioms
• Linting & Code Quality Best Practices - toolchain enforcement
• Errors as Values: Go's Error Philosophy - error culture

External Related Links

• Effective Go - Official guide to writing clear, idiomatic Go.
• Go Wiki – Learn - Curated community learning resources.
• Go Official Website / Documentation - Main documentation hub.
• Learning Go (2nd Edition) - Jon Bodner.
• Concurrency in Go - Katherine Cox-Buday.

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).