go-uber-style-guide

Core Mandates

Error Handling

• Handle Errors Once: Handle each error at most once. Do not log and return the same error.
• Don't Panic: Avoid

  panic

  in production. Return errors instead.

  panic

  is only for truly irrecoverable states (e.g., nil dereference) or program initialization (aborting at startup).
• Exit in Main: Call

  os.Exit

  or

  log.Fatal*

  only in

  main()

  . Prefer calling it at most once. All other functions must return errors.
• Type Assertion Safety: Always use the "comma ok" idiom (

  value, ok := interface{}.(Type)

  ) for type assertions.
• Error Wrapping: Use

  fmt.Errorf

  with

  %w

  to wrap errors for the caller to match, or

  %v

  to obfuscate. Avoid "failed to" prefixes.

Concurrency

• Channel Sizing: Channels should be unbuffered (size zero) or have a size of one. Any other size requires extreme justification and scrutiny.
• Goroutine Lifecycles: Never "fire-and-forget". Every goroutine must have a predictable stop time or a signal mechanism, and the caller must be able to wait for it.
• No Goroutines in

  init()

  :

  init()

  functions must not spawn goroutines. Manage background tasks via objects with explicit lifecycle methods.
• Atomic Operations: Use

  go.uber.org/atomic

  for type-safe atomic operations.

Data Integrity & Globals

• Copy Slices and Maps at Boundaries: Copy incoming slices/maps if you store them. Copy outgoing ones if they expose internal state.
• Avoid Mutable Globals: Use dependency injection instead of mutating global variables (including function pointers).
• No Shadowing: Do not use Go's predeclared identifiers (e.g.,

  error

  ,

  string

  ,

  make

  ,

  new

  ) as names.

  go vet

  should be clean.

Code Structure

• Consistency is Key: Above all, be consistent at the package level or higher.
• Minimize

  init()

  : Avoid

  init()

  unless necessary and deterministic. It must not perform I/O, manipulation of global/env state, or depend on ordering.
• Explicit Struct Initialization: Always use field names (

  MyStruct{Field: value}

  ). (Exception: test tables with <= 3 fields).
• Nil Slice Semantics: Return

  nil

  for empty slices. Check

  len(s) == 0

  for emptiness.

  var

  declared slices are immediately usable.

Expert Guidance

Pointers & Interfaces

• No Interface Pointers: Pass interfaces as values. Use a pointer only if methods must modify the underlying data.
• Compile-Time Interface Verification: Use

  var _ Interface = (*Type)(nil)

  to verify compliance at compile time where appropriate.
• Receiver Choice: Pointer receivers are only for pointers or addressable values. Value receivers work for both. Interfaces can be satisfied by pointers even for value receivers.

Concurrency & Synchronization

• Zero-Value Mutexes:

  sync.Mutex

  and

  sync.RWMutex

  are valid in their zero-value state. Do not use pointers to mutexes. Use non-pointer fields in structs.
• No Mutex Embedding: Do not embed mutexes in structs, even unexported ones.
• Synchronization: Use

  sync.WaitGroup

  for multiple goroutines, or

  chan struct{}

  (closed when done) for a single one.

Time Management

• time

  Package: Always use the

  "time"

  package for all time operations.
• Instants vs. Periods: Use

  time.Time

  for instants and

  time.Duration

  for periods.
• External Systems: Use

  time.Time

  /

  time.Duration

  with external systems. If not possible, use

  int

  /

  float64

  with unit in the name (e.g.,

  Millis

  ), or RFC 3339 strings for timestamps.
• Comparison: Use

  .AddDate

  for calendar days,

  .Add

  for absolute 24-hour periods.

Performance (Hot Path Only)

• strconv

  over

  fmt

  : Use

  strconv

  for primitive-to-string conversions.
• String-to-Byte: Convert fixed strings to

  []byte

  once and reuse.
• Capacity Hints: Specify capacity in

  make()

  for maps and slices where possible to minimize reallocations.

Code Style & Readability

• Line Length: Soft limit of 99 characters. Avoid horizontal scrolling.
• Grouping: Group related

  import

  ,

  const

  ,

  var

  , and

  type

  declarations. Group variables in functions if declared adjacently.
• Import Ordering: Two groups: Standard library first, then others, separated by a blank line.
• Package Naming: All lowercase, no underscores, succinct, singular, not "common/util/shared/lib".
• Function Naming: MixedCaps. Underscores allowed in tests for grouping.
• Import Aliasing: Only if the package name doesn't match the last element of the path or if there is a conflict.
• Ordering: Group by receiver. Sort by call order. Exported functions first. Utilities at the end.
• Nesting: Handle error/special cases first (early return/continue).
• Unnecessary Else: Replace

  if/else

  where a variable is set in both with a single update if possible.
• Unexported Global Prefix: Use

  _

  for unexported top-level

  var

  /

  const

  (exception:

  err

  prefix on unexported errors).
• Embedding: Place at the top of the struct, separated by a blank line. Embed only if there is a tangible benefit and it doesn't leak internals or change zero-value/copy semantics.
• Variable Declaration: Use

  :=

  for explicit values,

  var

  for default zero-values. Minimize scope.
• Naked Parameters: Use C-style comments

  /* paramName */

  for clarity. Use custom types instead of

  bool

  where appropriate.
• Raw Strings: Use backticks (

  `

  ) for multi-line or quoted strings.

Patterns

• Table-Driven Tests: Use the

  tests

  slice and

  tt

  case variable. Use

  give

  /

  want

  prefixes. Avoid complex logic inside subtests.
• Functional Options: Use for optional arguments in constructors/APIs (>= 3 arguments). Use an

  Option

  interface and an unexported

  options

  struct.

Tooling & Verification

• Tooling (Go 1.24+): Prefer

  go tool <toolname>

  for invoking project-local tools.
• Linting: Use

  golangci-lint

  as the runner. Use the configuration in assets/.golangci.yml as a baseline.
• Struct Tags: Always use field tags for marshaled structs (JSON, YAML).
• Leak Detection: Use

  go.uber.org/goleak

  for goroutine leaks.
• Format Strings: Declare format strings as

  const

  outside of

  Printf

  calls for

  go vet

  analysis.
• Printf Naming: End custom Printf-style functions with

  f

  .