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
%wwhen callers inspect sentinels. Opaque messages breakerrors.Ischains. - 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.sumdiffs atomically with imports. - Tag library releases with semver. Breaking changes require major bumps or
/v2paths. - Keep direct dependencies minimal and owned. Run
go mod why -mon 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 fixmodernizers 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
Where should a new developer start?
Effective Go as a Living Standard, then Go Rules Quickstart, then Tier A of this page.
Which checklist is highest priority for services?
Effective Go Rules, then Concurrency, then Security before launch.
Which checklist is highest priority for libraries?
API Design and Module rules before tagging v1.
How do rules relate to golangci-lint?
Automate objective subsets.
Keep judgment rules in review and ADRs.
Should we copy this list into our wiki?
Link here as canonical.
Add a short delta doc for org-only rules (logging vendor, RPC framework).
How often should teams revisit this summary?
Quarterly and after Go minor releases.
What if a rule conflicts with performance data?
Document benchmark evidence and scope the exception to the hot package.
Do TinyGo targets use the same tiers?
Tier A mostly applies.
Concurrency and stdlib subsets need build-tag scoped checklists.
Can agents enforce these rules?
Yes for format, vet, module tidy, and govulncheck.
Interface design and operability still need human review.
What is missing from this section?
Deep dives live in sibling sections: error-handling, packages-modules, security, performance-profiling, and linting-quality.
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
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).