Go Best Practices
| Pattern | When to apply |
|---|---|
| Minimal main | New binaries |
| Single bootstrap | App wiring across modes |
| Ordered shutdown | Long-running processes |
| Non-blocking fanout | Channel-based event systems |
| Concurrency testing | Any goroutine code |
| Layered config | Multi-source configuration |
| Cross-platform paths | File/config path resolution |
| Secure debug logging | HTTP client instrumentation |
| Golden test matrices | Rendering / output components |
| Focused linters | CI pipeline setup |
Read references/patterns.md for code examples.
Rules
- main.go is a stub. Call
cmd.Execute()and nothing else. Gate diagnostics (pprof) behind env vars. - One bootstrap path. All modes (interactive, headless, test) share the same initialization function. Two paths will drift.
- Ordered shutdown. Cancel dependents before their dependencies, then run independent cleanup in parallel under a timeout context. WaitGroup the parallel phase.
- Never block the sender. Non-blocking channel sends with an explicit drop policy. Log drops at debug level. Document the policy.
- Test concurrency mechanically.
testing/synctestfor deterministic timing,goleak.VerifyNonefor leak detection, dedicated regression tests for timer/channel deadlocks. - Explicit config precedence. Global → project → flags. Walk up from CWD to discover project configs, reverse so closest wins, deep-merge.
- Centralize platform paths. One function per concern. Resolution order: env override → XDG → platform default → fallback.
- Redact secrets in debug logs. Wrap
http.RoundTripper. Filter headers matching authorization, api-key, token, secret. Gate on debug level to skip allocation in prod. - Golden tests over matrices. Cross dimensions (layout × theme × size) as parallel subtests. Sweep continuous ranges to catch off-by-one bugs.
- Focused linters, not all linters. Enable what catches real bugs (bodyclose, noctx, tparallel). Disable noisy defaults. Add project-specific checks as scripts. Always
-racein tests.