Go Standards

Go Standards

Idiomatic Go for this codebase. Distilled from Effective Go, the Google Go Style Guide, and Go Code Review Comments. When in doubt, optimize for the reader: clarity over cleverness, simplicity over abstraction.

Always run gofmt -w . before finishing. CI fails on any unformatted file. Prefer goimports to keep imports grouped and sorted.

Naming

• Packages: short, lowercase, no underscores or camelCase (rpc, slog, not rpcClient or rpc_client). The package name is part of every identifier's path — avoid stutter: rpc.Client, not rpc.RPCClient.
• Exported identifiers: MixedCaps. Unexported: mixedCaps. Never snake_case.
• Getters: no Get prefix. A field owner is read via Owner(), not GetOwner(). (RPC method names mirroring an external API like GetVoteAccounts are the exception — they name the wire call, not a Go getter.)
• Interfaces: single-method interfaces take the method name + -er (Reader, Watcher, Collector).
• Length tracks scope: i, r, b are fine in a 3-line loop; use descriptive names for package-level or long-lived values. Receiver names are 1–2 chars and consistent across all methods of a type (c *Client, not this or self).
• Acronyms keep their case: URL, ID, RPC, HTTP — parseURL, userID, serveHTTP. Not parseUrl or userId.
• Errors: sentinel values are ErrFoo; error types are FooError.

Errors

• Return error as the last return value. Handle it — never discard with _ unless you can articulate why.
• Add context when propagating, and wrap with %w so callers can errors.Is/errors.As:

  if err != nil {
      return fmt.Errorf("fetching block %d: %w", slot, err)
  }

• Error strings are lowercase, no trailing punctuation (they get wrapped): "connection refused", not "Connection refused.".
• Compare with errors.Is (sentinels) and errors.As (typed errors). Do not compare with == across wrap boundaries or string-match on err.Error().
• Keep the happy path at minimum indentation. Return early on error rather than nesting the success case in an else:

  if err != nil {
      return err
  }
  // happy path continues unindented

• panic is for programmer bugs / truly unrecoverable state, not ordinary error flow. Library code returns errors.

Control Flow & Style

• No else after a block that ends in return/continue/break.
• Use defer for cleanup (Close, Unlock, Done) immediately after acquiring the resource — it runs even on panic and keeps acquire/release adjacent.
• Prefer for range. Zero values are usable: a nil slice appends fine, a nil map reads fine (writes panic), a zero sync.Mutex is unlocked and ready.
• Slices: make([]T, 0, n) when you know the capacity. Distinguish nil from empty only when the API contract does.
• Accept interfaces, return concrete types. Don't define an interface until there are ≥2 implementations or a real seam for testing — Go interfaces are satisfied implicitly, so add them at the consumer, not preemptively at the producer.
• Keep interfaces small. The bigger the interface, the weaker the abstraction.