idiomatic-go

Idiomatic Go

The conventions here come from Effective Go and Go Code Review Comments — the documents that codify what Go reviewers reject pull requests over. The content is filtered to the rules that strong models still slip on, so basic syntax, gofmt usage, and well-known mechanics (LIFO defer, new vs make, channel basics) are not repeated here.

The guiding principle is clear is better than clever (Rob Pike's phrasing, elaborated in Dave Cheney's article of the same name). When choosing between a concise/clever construction and an explicit/plain one, pick the explicit one. Code is decoded, not skimmed, and it outlives the person who wrote it.

APIs that require Go 1.22 or later are called out inline below. Older stable symbols (errors.Is, fmt.Errorf with %w, slices.Clone, and similar) are not annotated.

Reference files

Load these as needed — don't read them upfront. This file has the rules and decision points; the references hold the long tail.

• references/naming.md — the full initialism table with the awkward cases (OAuth, IPv4, gRPC, IDs, HTTPSProxy), worked naming examples, deeper package-naming guidance (why util/common/misc collect garbage and how to split them), import grouping, and file naming with build constraints. Read this when naming anything exported or organizing a new package.
• references/interfaces-and-errors.md — interface placement worked end-to-end, embedding, compile-time satisfaction checks; sentinel errors vs custom error types vs fmt.Errorf; the errors.Is/As/Join model and when not to wrap; structured errors; panic/recover discipline. Read this when designing an API, writing a non-trivial error type, or wrapping errors across abstraction boundaries.
• references/concurrency-patterns.md — the context.Context contract end-to-end, the four ways a goroutine exits, the for select skeleton, channel-direction signatures, semaphore and leaky-buffer patterns, sync.Once/WaitGroup/errgroup decisions, channel-closing rules, idempotent shutdown against concurrent registration (a coordinator's shutdown safe to call twice and race-free against concurrent subscriber registration), and the anti-patterns (sleeping in tests, polling, fire-and-forget goroutines). Read this when starting a goroutine, designing a cancellable operation, or reviewing concurrent code.
• references/language-engineering.md — patterns specific to Go tools for programming languages (parsers, language servers/LSP, type checkers, validators, DSLs) that go beyond baseline idiomatic Go: nil-safe AST navigation, callback-vs-iterator traversal, optional capability interfaces, non-nil empty sentinels, typed source coordinates and UTF-16 columns, editor-overlay text handles, lazy scope chains, typed/untyped references and once-only resolution with cycle detection, phased incremental builds and the write-to-read lock downgrade, keeping the domain free of the LSP protocol, and completion as a parser capability. Read this when working on a language implementation, a DSL, or a toolkit built on a Go language framework — not for ordinary application code.